O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

Automatizar builds em resposta a eventos de webhook

Com o Cloud Build, é possível definir gatilhos de webhook para autenticar e aceitar eventos de webhook recebidos. Esses eventos, enviados para um URL personalizado, permitem conectar sistemas externos e plataformas de gerenciamento de código-fonte, como Bitbucket.com, Bitbucket Server ou GitLab, diretamente ao Cloud Build.

Com gatilhos de webhook, é possível especificar uma configuração do build inline em vez de um repositório de origem. Essa configuração inline oferece controle sobre as operações do Git e o fluxo de trabalho de build. Para automatizar builds em eventos de repositório, use os gatilhos de repositório do Cloud Build, que se integram diretamente a provedores como GitHub e GitLab.

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 de build inline oferece controle sobre as operações do Git e permite definir o restante do build.

Nesta página, mostramos como criar gatilhos de webhook para automatizar builds em resposta a eventos de webhook.

Antes de começar

Ative as APIs Cloud Build e Secret Manager, se ainda não estiverem ativadas.
Funções necessárias para ativar APIs
Para ativar APIs, você precisa da permissão serviceusage.services.enable. Se você criou o projeto, provavelmente já tem essa permissão pelo papel de proprietário (roles/owner). Caso contrário, é possível conseguir essa permissão pelo papel de administrador do Service Usage (roles/serviceusage.serviceUsageAdmin). Saiba como conceder papéis.
Ativar as APIs

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

Observação :se você já instalou a CLI gcloud, verifique se tem a versão mais recente disponível executando gcloud components update.
Se o gatilho de webhook usar um repositório do Cloud Build como origem, conheça os repositórios do Cloud Build.

Criar gatilhos de webhook

Console

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

Acesse a página Gatilhos:

Abrir a página “Gatilhos de compilação”
Selecione seu projeto na parte superior da página e clique em Abrir.
Clique em Criar gatilho.
Preencha as configurações de gatilho a seguir:
- Nome: nome do acionador.
- Região: selecione a região do gatilho.
  - Se o arquivo de configuração de build associado ao gatilho especificar um pool particular, o Cloud Build 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 particular.
  - 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. Você vai precisar de um secret para autenticar eventos de webhook recebidos. É possível criar um novo secret ou usar um existente. Esse secret é separado do secret associado à sua chave SSH.
  
  Para criar um secret:
  1. Selecione Usar um novo secret (gerado pelo Cloud Build).
  2. Clique em Criar secret.
    
    A caixa de diálogo Criar um secret do webhook vai aparecer.
  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 existente ou criar um próprio.
  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 do Secret Manager à sua conta de serviço.
    
    Depois de criar ou selecionar o secret, você vai encontrar uma prévia do URL do webhook. O URL vai conter uma chave de API gerada pelo Cloud Build e o secret. Se o Cloud Build não conseguir recuperar sua chave de API, adicione-a manualmente ao URL ou saiba como conseguir uma chave de API se ainda não tiver uma.
    
    Use o URL para invocar um evento de webhook fazendo uma solicitação HTTP com o método POST.
    
    Depois de concluir essas etapas, o papel de Acessador de Secrets do Secret Manager será concedido automaticamente ao agente de serviço do Cloud Build, service-${PROJECT_NUMBER}@gcp-sa-cloudbuild.iam.gserviceaccount.com. Se esse papel não for adicionado automaticamente ao agente de serviço, siga as etapas descritas em Como conceder o papel do Secret Manager à sua conta de serviço.
- Origem (opcional): se você estiver especificando uma configuração de build inline, não será necessário especificar uma origem. Caso contrário, faça o seguinte:
  - Geração de repositórios: selecione 2ª geração.
  - Repositório: na lista de repositórios disponíveis, selecione aquele que você quer usar para criar. A região do repositório precisa corresponder à região do gatilho.
  - 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 pull como seu Evento, escolha uma das seguintes opções para controlar se o gatilho invoca automaticamente um build:
    
    Aviso: qualquer usuário com acesso de leitura ao repositório pode enviar uma solicitação de envio, que pode executar um build que inclui alterações no código-fonte na solicitação de envio. Para desativar esse comportamento, recomendamos o uso de aprovações manuais para bloquear builds ao fazer solicitações de pull em repositórios públicos. Saiba mais sobre os privilégios de tempo de compilação dos gatilhos.
    - Obrigatório, exceto para proprietários e colaboradores: quando uma solicitação de pull é criada ou atualizada por um proprietário ou colaborador do repositório, os builds são executados automaticamente. Se um colaborador externo iniciar a ação, os builds serão executados somente depois que um proprietário ou colaborador comentar /gcbrun na solicitação de envio.
    - Obrigatório: quando uma solicitação de envio é criada ou atualizada por qualquer colaborador, os builds são executados somente depois que um proprietário ou colaborador comenta /gcbrun na solicitação de envio. As versões são executadas sempre que uma alteração é feita em uma solicitação de envio.
    - Não obrigatório: quando uma solicitação de envio é criada ou atualizada por qualquer colaborador, os builds são executados automaticamente.
- 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 especificou um repositório de origem, selecione um arquivo de configuração de build Inline como sua opção de configuração:
  - Type: selecione o tipo de configuração a ser usado para o 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 o local do arquivo de configuração do build, o diretório Dockerfile ou o diretório de 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 do Dockerfile ou do buildpack, você verá uma prévia do comando docker build ou pack que o build vai 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 criar o arquivo de configuração do build no console doGoogle Cloud usando a sintaxe YAML ou JSON. Clique em Concluído para salvar a configuração do build.
      
      Observação: a compatibilidade com a configuração do build inline não está disponível para Dockerfile ou pacotes de criação.
  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 ele vai executar um build com base nas variáveis de substituição.
Clique em Criar para criar seu gatilho de compilação.

gcloud

Para criar um gatilho do webhook:

gcloud builds triggers create webhook \
  --trigger-config=TRIGGER_CONFIG_PATH \
  --name=TRIGGER_NAME \
  --description=DESCRIPTION \
  --region=REGION \
  --secret=projects/PROJECT_ID/secrets/SECRET_NAME/versions/SECRET_VERSION \
  --service-account=SERVICE_ACCOUNT \ 
  --repository=projects/PROJECT_ID/locations/REGION/connections/CONNECTION_NAME/repositories/REPO_NAME \ 
  --build-config=PATH_TO_BUILD_CONFIG \
  --inline-config=PATH_TO_INLINE_BUILD_CONFIG \
  --dockerfile=DOCKERFILE \
  --dockerfile-dir=DOCKERFILE_DIR \
  --dockerfile-image=DOCKERFILE_IMAGE \
  --tag=TAG_NAME \
  --branch=BRANCH_NAME \
  --substitutions=_SUB_ONE=SUBSTITUTION \
  --subscription-filter=FILTER \
  --require-approval

Em que:

TRIGGER_CONFIG_PATH é o caminho para um arquivo de configuração de gatilho. Se você usar um arquivo de configuração de gatilho, os campos name, description, region, secret, service-account, subscription-filter e substitution precisarão permanecer indefinidos. Para mais informações, consulte BuildTrigger na documentação de referência do Cloud Build.
TRIGGER_NAME é o nome do gatilho.
DESCRIPTION (opcional) é uma descrição do gatilho.
REGION é a região do gatilho. Esse valor precisa ser uma região diferente de "global".
SECRET_NAME é o nome do secret armazenado no Secret Manager.
SECRET_VERSION é a versão associada ao secret, conforme armazenado no Secret Manager.
SERVICE_ACCOUNT é a conta de serviço usada para executar todas as operações controladas pelo usuário relacionadas ao gatilho de compilação. Se você não definir uma conta de serviço, o Cloud Build vai usar a conta de serviço padrão do Cloud Build.
PROJECT_ID é o ID do projeto do Google Cloud .
CONNECTION_NAME é o nome da conexão de host.
REPO_NAME é o nome do repositório.
PATH_TO_BUILD_CONFIG é o caminho para um arquivo de configuração de build. Use esse parâmetro se o gatilho se referir a um arquivo de configuração de build em um repositório do Cloud Build. Se você definir esse parâmetro, não será possível definir um inline-config ou usar parâmetros para um Dockerfile.
PATH_TO_INLINE_BUILD_CONFIG é o caminho para uma configuração de build inline. Use esse parâmetro se o gatilho se referir a um arquivo de configuração de build local. Se você definir esse parâmetro, não será possível definir um build-config ou usar parâmetros para um Dockerfile.
DOCKERFILE é o caminho para um Dockerfile. Use esse parâmetro se o gatilho se referir a um Dockerfile. Se você definir parâmetros do Dockerfile, não será possível definir um build-config ou um inline-config.
DOCKERFILE_DIR é o diretório do Dockerfile.
DOCKERFILE_IMAGE é o nome da imagem Docker criada pelo Cloud Build.
BRANCH_NAME é o nome da ramificação, se você quiser definir o gatilho para criar em uma ramificação. Se você definir esse parâmetro, não será possível definir um tag.
TAG_NAME é o nome da tag se você quiser definir o gatilho para criar em uma tag. Se você definir esse parâmetro, não será possível definir um branch.
SUBSTITUTION (opcional) são parâmetros a serem substituídos na especificação do build. Por exemplo, _SUB_ONE='$(body.message.test)',_SUB_TWO='$(body.message.output)'.
FILTER (opcional) é uma expressão de filtro CEL para o gatilho, como '_SUB_ONE == "prod"'.
(Opcional) Quando --require-approval está presente no comando, o Cloud Build exige aprovação manual para builds acionados.

Invocar um evento de webhook

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 "{}"

(Opcional) Conceder o papel do Secret Manager à sua conta de serviço

Quando você configura o secret durante a criação do gatilho de webhook, na maioria dos casos, o Cloud Build concede automaticamente o papel de Acessador de secrets do Secret Manager às contas de serviço que precisam dele. No entanto, se você usar um secret atual, talvez também precise conceder manualmente o papel de acessador de secrets do Secret Manager à sua conta de serviço do Cloud Build:

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

Abrir a página do IAM
Opcional: para ver as contas fornecidas pelo Google, marque a caixa de seleção Incluir concessões de papel fornecidas pelo Google.
Anote a conta de serviço do build a que você quer conceder o papel.
Abra a página do Secret Manager no console do Google Cloud :

Abra a página do Secret Manager
Clique no nome do secret.

Você verá a página Detalhes do secret.
1. Clique na guia Permissões.
2. Clique em Conceder acesso.
  
  O painel Conceder acesso vai aparecer.
3. Na seção Adicionar principais, adicione o e-mail associado à conta de serviço do build.
4. Na seção Atribuir papéis, selecione Secret Manager > Acessador de secrets do Secret Manager.
5. Clique em Salvar.

(Opcional) Conseguir uma chave de API

Para autenticar um evento de webhook recebido, você precisa de uma chave de API. Essa chave de API faz parte do secret que você escolhe ao configurar o gatilho de webhook. Se você ainda não tiver uma chave de API ou se o Cloud Build não tiver conseguido recuperar uma ao configurar o secret no console do Google Cloud , crie uma chave de API manualmente:

Para gerar uma chave de API:

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

Abra a página Credenciais
Clique em Criar credenciais.
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.
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.

A seguir

Saiba como criar e gerenciar gatilhos.
Saiba como criar repositórios hospedados no Bitbucket Server.
Saiba como iniciar versões manualmente.
Saiba como ver os resultados da build.
Saiba como resolver erros de build.