Configurar webhooks

Nesta página, descrevemos como configurar webhooks no Secure Source Manager.

Os webhooks são solicitações HTTP acionadas por um evento no Secure Source Manager e enviadas para um URL especificado pelo usuário.

Antes de começar

  1. Crie uma instância do Secure Source Manager.
  2. Crie um repositório do Secure Source Manager.

Funções exigidas

Para receber as permissões necessárias para criar webhooks, peça ao administrador os seguintes papéis do IAM:

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível conseguir as permissões necessárias usando papéis personalizados ou outros papéis predefinidos.

Para informações sobre como conceder papéis do Secure Source Manager, consulte Controle de acesso com o IAM e Conceder acesso à instância aos usuários.

Configurar um webhook

Console

  1. Na interface da Web do Secure Source Manager, navegue até o repositório em que você quer criar um webhook.
  2. Clique em Configurações.
  3. Clique em Webhooks e em Adicionar webhook.

  4. No campo ID do hook, insira um ID para o webhook.

  5. No campo URL de destino, insira o URL do webhook. Por exemplo, se você quiser acionar um build no Jenkins, configure um gatilho de webhook e insira o URL do gatilho do Jenkins aqui para acionar o build no Jenkins.

  6. Na seção Acionar em, selecione uma das seguintes opções:

    • Push: para acionar um push no repositório.
    • Estado da solicitação de pull mudou: para acionar uma mudança no estado da solicitação de pull.

  7. Configure a autenticação do webhook usando uma string de consulta sensível ou a autenticação da conta de serviço:

    • String de consulta sensível:

      A string de consulta sensível consiste nos valores key e secret do URL do webhook, incluindo os prefixos key= e secret=. Para configurar a autorização de string de consulta sensível, remova esses valores do URL do webhook e adicione-os ao campo String de consulta sensível:

      1. Exclua o ? do URL do webhook.
      2. Copie a parte restante do URL, começando com key=.
      3. Cole essa parte no campo String de consulta sensível.
      4. Exclua a mesma parte do URL do webhook.

      Por exemplo, considerando o seguinte URL: https://cloudbuild.googleapis.com/v1/projects/my-project/triggers/test-trigger:webhook?key=eitIfKhYnv0LrkdsyHqIros8fbsheKRIslfsdngf&secret=My%20Secret%20

      Sua string de consulta sensível seria: key=eitIfKhYnv0LrkdsyHqIros8fbsheKRIslfsdngf&secret=My%20Secret%20

    • Autenticação de conta de serviço:

      1. Verifique se o repositório tem uma conta de serviço com os papéis do IAM definidos para autenticação de conta de serviço em Papéis obrigatórios.
      2. Selecione Ativar a autenticação da conta de serviço.

  8. Se você selecionou Push, insira uma lista de permissões para eventos de push no campo Filtro de ramificação.

    O campo Filtro de ramificação usa o padrão glob, e apenas operações nas ramificações correspondentes vão acionar um gatilho de compilação. Por exemplo, {main,dev} é acionado em eventos de envio para as ramificações main e dev. Se o campo estiver vazio ou for *, os eventos de push de todas as ramificações serão informados. Para informações sobre a sintaxe, consulte a documentação do glob.

  9. Clique em Add webhook.

  10. O webhook é exibido na página Webhooks.

REST

Para criar um webhook, invoque o método hooks.create enviando uma solicitação POST ao endpoint hooks. É possível autenticar seu webhook usando uma string de consulta sensível ou a autenticação da conta de serviço.

  • String de consulta sensível

    curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "targetUri": "https://${SERVICE_NAME}.app/webhook?key=${KEY}&secret=${SECRET}",
    "events": ["PUSH"]
    "sensitiveQueryString": "${SENSITIVE_QUERY_STRING_VALUE}"
  }' \
  "https://securesourcemanager.googleapis.com/v1/projects/${PROJECT_ID}/locations/${LOCATION}/repositories/${REPOSITORY}/hooks?hook_id=${HOOK_ID}"

    O SENSITIVE_QUERY_STRING_VALUE precisa ser o valor de key e secret no URL do webhook. Por exemplo, se o key for eitIfKhYnv0LrkdsyHqIros8fbsheKRIslfsdngf e o secret for MySecret, o SENSITIVE_QUERY_STRING_VALUE será key=eitIfKhYnv0LrkdsyHqIros8fbsheKRIslfsdngf&secret=MySecret.

  • Autenticação da conta de serviço

    curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "targetUri": "https://${SERVICE_NAME}.app/webhook",
    "events": ["PUSH"],
    "serviceAccountAuth": true
  }' \
  "https://securesourcemanager.googleapis.com/v1/projects/${PROJECT_ID}/locations/${LOCATION}/repositories/${REPOSITORY}/hooks?hook_id=${HOOK_ID}"

Testar o webhook

  1. Na página Webhooks do Secure Source Manager, clique no webhook que você quer testar.

  2. Role até a parte de baixo da página e clique em Testar entrega.

    Um evento substituto é adicionado à fila de entrega. Pode levar alguns segundos para que ele apareça no histórico de entrega.

  3. Também é possível usar um comando git para enviar ou mesclar uma solicitação de envio para testar o webhook.

  4. Verifique o status do build ou evento acionado no histórico de builds do serviço em que você configurou o gatilho de webhook.

  5. Você também pode conferir a Solicitação e a Resposta da entrega de teste na seção Entregas recentes da página do webhook do Secure Source Manager depois de enviar a primeira entrega de teste.

Substituir variáveis YAML do Cloud Build por dados de payload

Se você estiver usando webhooks para se conectar ao Cloud Build, poderá substituir variáveis YAML do Cloud Build por dados de payload de webhook do Secure Source Manager.

  1. Na página Webhooks do Secure Source Manager, na seção Entregas recentes, clique na linha de cima.

    O cabeçalho Request e o conteúdo enviado pelo payload do webhook são mostrados.

  2. Acesse o painel do Cloud Build e clique em Gatilhos.

  3. Clique no gatilho que você quer configurar.

  4. Na seção "Avançado", em Variáveis de substituição, clique em + Adicionar variável.

  5. Insira o nome e o valor da variável. O prefixo do valor é body.

    Por exemplo, para substituir _REPO_URL pelo campo de dados do payload repository.clone_url e _COMMIT_SHA pelo sha do commit mais recente no YAML do Cloud Build, insira os seguintes nomes e valores:

    • Variável 1: _REPO_URL Valor 1: $(body.repository.clone_url)
    • Variável 2: _COMMIT_SHA Valor 2: $(body.after)

    O arquivo YAML do Cloud Build é semelhante a este:

    steps:
- name: gcr.io/cloud-builders/git
  env:
  - '_REPO_URL=$_REPO_URL'
  - '_COMMIT_SHA=$_COMMIT_SHA'
  script: |
    #!/bin/sh
    git clone ${_REPO_URL} /workspace
    cd /workspace
    git reset --hard ${_COMMIT_SHA}

A seguir