Automatizar builds em resposta a eventos de webhook

O Cloud Build permite definir gatilhos de webhook, que podem autenticar e aceitar eventos de webhook de entrada. Esses eventos, enviados para um URL personalizado, permitem conectar diretamente sistemas externos e de gerenciamento de código-fonte externo, como Bitbucket.com, Bitbucket Server ou GitLab, ao Cloud Build por meio de eventos do webhook.

Com os gatilhos de webhook, você pode definir um arquivo de configuração do build inline em vez de especificar uma origem ao criar seu gatilho. A configuração do build inline permite que você tenha controle sobre as operações do git e defina o restante do build.

Esta página descreve como criar gatilhos de webhook para automatizar builds em resposta a eventos de webhook.

Antes de começar

  • Enable the Cloud Build and Secret Manager APIs.

    Enable the APIs

  • Para usar os comandos gcloud nesta página, instale a CLI do Google Cloud.

Como criar gatilhos de webhook

Console

Para criar um gatilho de webhook usando o console do Google Cloud:

  1. Acesse a página Gatilhos:

    Abrir a página “Gatilhos de compilação”

  2. Selecione seu projeto na parte superior da página e clique em Abrir.

  3. Clique em Criar gatilho.

  4. Preencha as configurações de gatilho a seguir:

    • Nome: nome do gatilho.

    • Região: selecione a região do gatilho.

      • Se o arquivo de configuração do build associado ao acionador especificar um pool particular, o Cloud Build vai usar o pool particular para executar o build. Nesse caso, a região especificada no gatilho precisa corresponder à região em que você criou o pool privado.
      • Se o arquivo de configuração do build associado ao gatilho não especificar um pool particular, o Cloud Build vai usar o pool padrão para executar o build na mesma região do gatilho.

    • Descrição (opcional): uma descrição do gatilho.

    • Evento: selecione Evento de webhook para configurar o gatilho para iniciar builds em resposta a eventos de webhook recebidos.

    • URL do webhook: use o URL do webhook para autenticar eventos de webhook recebidos.

      • Secret: você precisará de um secret para autenticar eventos de webhook recebidos. É possível criar um novo secret ou usar um existente. Isso é separado do secret associado à sua chave SSH.

        Para criar um novo secret:

        1. Selecione Usar um novo secret (gerado pelo Cloud Build).

        2. Clique em Criar secret.

          Você verá a caixa pop-up Criar um secret do webhook.

        3. No campo Nome do secret, insira um nome para o secret.

        4. Clique em Criar secret para salvar seu secret, que será criado e armazenado automaticamente para você no Secret Manager.

        Para usar um secret existente:

        1. Selecione Usar um secret ou criar um.
        2. No campo Secret, selecione o nome do secret que você quer usar no menu suspenso ou siga as instruções para adicionar um secret por ID do recurso.
        3. No campo Versão do secret, selecione sua versão do secret no menu suspenso.

        Se você usar um secret existente, talvez seja necessário conceder manualmente o papel de acessador do secret do Secret Manager à sua conta de serviço do Cloud Build, service-${PROJECT_NUMBER}@gcp-sa-cloudbuild.iam.gserviceaccount.com. Para saber mais, consulte Como conceder o papel de Secret Manager à conta de serviço.

      Depois de criar ou selecionar o secret, você verá uma visualização do URL do webhook. O URL vai conter uma chave de API gerada pelo Cloud Build e o secret. Se o Cloud Build for incapaz de recuperar a chave de API, será possível adicioná-la manualmente ao URL ou aprender a conseguir uma chave de API se você não tiver uma ainda.

      É possível usar o URL para invocar um evento de webhook fazendo uma solicitação HTTP com o método POST.

      Use o comando a seguir para invocar um evento de webhook:

      curl -X POST -H "Content-type: application/json" "https://cloudbuild.googleapis.com/v1/projects/${PROJECT_ID}/locations/${REGION}/triggers/${TRIGGER_NAME}:webhook?key=${API_KEY}&secret=${SECRET_VALUE}&trigger=${TRIGGER_NAME}&projectId=${PROJECT_ID}" -d "{}"

      Depois de concluir essas etapas, o papel Acessador do secret do Secret Manager será concedido automaticamente ao agente de serviço do Cloud Build, service-${PROJECT_NUMBER}@gcp-sa-cloudbuild.iam.gserviceaccount.com. Se você não encontrar essa função automaticamente ao seu agente de serviço, faça o seguinte etapas descritas em Como conceder o papel de Secret Manager à conta de serviço.

    • Origem (opcional): selecione a origem a ser criada quando o gatilho do webhook for executado. Se você estiver especificando uma configuração do build inline, não será necessário especificar a origem a seguir. É possível especificar 1a geração ou Segunda geração como origem. Para saber mais, consulte Repositórios do Cloud Build.

      • Repositório: na lista de repositórios disponíveis, selecione o repositório que você quer.

      • Ramificação ou Tag: especifique uma expressão regular correspondente ao valor da ramificação ou da tag. Para ver informações sobre a sintaxe aceitável de expressões regulares, consulte Sintaxe de RE2 (em inglês).

      • Controle de comentários: se você selecionou Solicitação de envio (somente aplicativo GitHub) como seu Evento, escolha uma das seguintes opções para controlar se um build será executado automaticamente pelo gatilho:

        • Obrigatório, exceto para proprietários e colaboradores: quando uma solicitação de envio for criada ou atualizada por um proprietário ou colaborador de repositório, os builds são executados automaticamente pelo gatilho. Se um colaborador externo iniciar a ação, os builds serão executadas somente depois que um proprietário ou colaborador comentar a /gcbrun na solicitação de envio.

        • Obrigatório: quando uma solicitação de envio é criada ou atualizada por qualquer colaborador, os builds só serão executados depois que um proprietário ou colaborador comentar /gcbrun na solicitação de envio. Construções são executados sempre que uma alteração é feita em uma solicitação de envio.

        • Não necessário: quando uma solicitação de envio é criada ou atualizada por qualquer colaborador, os builds são executados automaticamente por gatilhos.

    • Configuração: selecione o arquivo de configuração do build localizado no seu repositório remoto ou crie um arquivo de configuração do build inline para usar no build. Se você não tiver especificado um repositório de origem, será necessário selecionar um arquivo de configuração do build Inline como opção de configuração.

      • Tipo: selecione o tipo de configuração para usar no seu build.
        • Arquivo de configuração do Cloud Build (yaml ou json): use um arquivo de configuração do build na sua configuração.
        • Dockerfile: use um Dockerfile para sua configuração.
        • Buildpacks: use os buildpacks na sua configuração.

      • Local: especifique o local de configuração.

        • Repositório: se o arquivo de configuração estiver localizado no repositório remoto, forneça a localização do arquivo de configuração de build, o Dockerfile diretório de build ou o diretório buildpacks. Se o tipo de configuração do build for um Dockerfile ou um buildpack, você precisará fornecer um nome para a imagem resultante e, opcionalmente, um tempo limite para o seu build. Depois de fornecer o nome da imagem Dockerfile ou do buildpack, você verá uma visualização do comando docker build ou pack que seu build executará.
        • Variáveis de ambiente de pacote (opcional): se você tiver selecionado buildpacks como tipo de configuração, clique em Adicionar variável de ambiente de pacote para especificar os valores e variáveis de ambiente do buildpack. Para saber mais sobre as variáveis de ambiente de buildpack, consulte Variáveis de ambiente.

        • Inline: se você selecionou o arquivo de configuração do Cloud Build (yaml ou json) como opção de configuração, pode especificar a configuração do build inline. Clique em Abrir editor para gravar o arquivo de configuração do build no Console do Google Cloud usando a sintaxe YAML ou JSON. Clique em Concluído para salvar a configuração do build.

      No exemplo a seguir, os logs do arquivo de configuração do build inline ecoam "hello world":

       steps:
 - name: 'ubuntu'
   args: ['echo', 'hello world']

    • Substituições (opcional): se você tiver selecionado o arquivo de configuração do build como sua opção de configuração do build ou criado um arquivo de configuração do build inline, será possível definir as variáveis de substituição específicas do gatilho usando este campo. Também é possível obter dados usando vinculações de payload ao definir valores de variáveis de substituição.

    • Filtros (opcional): é possível criar uma regra em um gatilho que determina se o gatilho executará um build com base nas variáveis de substituição.

  5. Clique em Criar para criar seu gatilho de compilação.

gcloud

Para criar um gatilho do webhook:

gcloud builds triggers create webhook \
  --region=REGION \
  --name=TRIGGER_NAME \
  --repository=projects/PROJECT_ID/locations/REGION/connections/CONNECTION_NAME/repositories/REPO_NAME \
  --secret=projects/PROJECT_ID/secrets/SECRET_NAME/versions/SECRET_VERSION \
  --substitutions=_SUB_ONE='$(body.message.test)',_SUB_TWO='$(body.message.output)' \
  --subscription-filter='_SUB_ONE == "prod"' \
  --inline-config=PATH_TO_INLINE_BUILD_CONFIG \
  --tag=TAG_NAME
  # --build-config=PATH_TO_BUILD_CONFIG \
  # --branch=BRANCH_NAME

Em que:

  • REGION é a região do acionador.
  • TRIGGER_NAME é o nome do gatilho.
  • PROJECT_ID é seu ID do projeto do Cloud.
  • CONNECTION_NAME é o nome da conexão de host.
  • REPO_NAME é o nome do repositório;
  • SECRET_NAME é o nome do secret, conforme armazenado no Secret Manager.
  • SECRET_VERSION é a versão associada ao seu como armazenado no Secret Manager.
  • PATH_TO_INLINE_BUILD_CONFIG é o caminho para o arquivo de configuração do build inline se você usar --inline-config.
  • TAG_NAME é o nome da tag se você quiser definir o gatilho para criar em uma tag.
  • PATH_TO_BUILD_CONFIG é o caminho para o arquivo de configuração do build se você usar --build-config.
  • BRANCH_NAME é o nome da ramificação, caso você queira que o gatilho crie em uma ramificação.

(Opcional) Como receber uma chave de API

Para autenticar o evento de webhook de entrada, você precisa de uma chave de API.

Para gerar uma chave de API:

  1. Abra a página Credenciais no console do Google Cloud:

    Abra a página Credenciais

  2. Clique em Criar credenciais.

  3. Clique em Chave de API.

    Você vai ver uma caixa de diálogo com a chave de API criada. Anote a sua chave de API.

  4. Se quiser restringir a chave para aplicativos de produto, clique em Restringir chave para concluir as etapas adicionais para protegê-la. Caso contrário, clique em Fechar.

    Para saber como restringir sua chave, consulte Como aplicar restrições de chave de API.

(Opcional) Como conceder o papel de Secret Manager à conta de serviço

O Cloud Build concede automaticamente o papel de Acessador de secret do Secret Manager às contas de serviço que exigem esse papel durante a configuração do secret. Se esse papel não for concedido automaticamente à conta de serviço necessária, conclua as etapas a seguir para adicioná-lo manualmente para que sua conta de serviço tenha acesso ao secret:

  1. Abra a página do IAM no console do Google Cloud:

    Abrir a página do IAM

  2. Opcional: para ver as contas fornecidas pelo Google, marque a caixa de seleção Incluir concessões de papel fornecidas pelo Google.

  3. Anote a conta de serviço do build a que você quer conceder o papel.

  4. Abra a página do Secret Manager no console do Google Cloud:

    Abrir a página "Gerenciador de secrets"

  5. Clique no nome do secret.

    Você verá a página Detalhes do secret.

    1. Clique na guia Permissões.

    2. Clique em Conceder acesso.

      Você verá o painel Conceder acesso.

    3. Na seção Adicionar participantes, adicione o e-mail associado à conta de serviço do build.

    4. Na seção Atribuir papéis, selecione Secret Manager > Acesso de secret do Secret Manager

    5. Clique em Salvar.

A seguir