Como criar gatilhos de webhook

O Cloud Build permite definir acionadores 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 de compilação in-line em vez de especificar uma origem ao criar seu gatilho. A configuração de compilação in-line permite que você tenha controle sobre as operações do git e defina o restante do build.

Nesta página, descrevemos como criar gatilhos de webhook.

Antes de começar

  • Ative as APIs Cloud Build and Secret Manager.

    Ative as APIs

  • Para usar os comandos gcloud nesta página, instale o SDK do 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.
    • 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.

      • Secret: você precisará de um secret para autenticar eventos de webhook recebidos. É possível criar um novo secret ou usar um existente.

        Para criar um novo secret:

        1. Selecione Criar novo.
        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 sua chave secreta, que será criada e armazenada automaticamente para você no Secret Manager.

        Para usar um secret atual, siga estas etapas:

        1. Selecione Usar existente.
        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.

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

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

       curl -X POST -H "application/json" "https://cloudbuild.googleapis.com/v1/projects/${PROJECT_NAME}/triggers/${TRIGGER_NAME}:webhook?key=${API_KEY}&secret=${SECRET_VALUE}" -d "{}"
      

      Depois de concluir essas etapas, o papel Administrador de secrets do Secret Manager será concedido automaticamente à sua conta de serviço do Cloud Build, service-${PROJECT_NUMBER}@gcp-sa-cloudbuild.iam.gserviceaccount.com. Se você não vir esse papel automaticamente na sua conta de serviço, conclua as etapas a seguir descritas em Como conceder o papel de Secret Manager à sua conta de serviço.

    • Origem (opcional): selecione o repositório a ser criado quando o gatilho do webhook for executado. Se você estiver especificando uma configuração de compilação in-line, não será necessário especificar a origem a seguir.

    • Revisão (opcional): selecione a ramificação ou tag a ser criada quando o gatilho do webhook for executado. Se você estiver especificando uma configuração de compilação in-line, não será necessário especificar as seguintes revisões.

      • Ramificação: (opcional) defina um gatilho para a ramificação. É preciso especificar um valor literal. Expressões regulares não são compatíveis.
      • Tag (opcional): defina um acionador para criar com base nessa tag. É preciso especificar um valor literal. As expressões regulares não são compatíveis.
    • Configuração: selecione o arquivo de configuração da versão localizado no seu repositório remoto ou crie um arquivo de configuração de versão in-line para usar na versão. Se você não tiver especificado um repositório de origem, será necessário selecionar um arquivo de configuração de compilação Inline como opção de configuração.

      • Type (link em inglês): selecione o tipo de configuração a ser usado para seu build.
        • Arquivo de configuração do Cloud Build (yaml ou json): use um arquivo de configuração de versão para 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 no seu repositório remoto, forneça o local do arquivo de configuração do build, o Dockerfile } ou o diretório buildpacks. Se o tipo de configuração de build for um Dockerfile ou um buildpack, você precisará fornecer um nome para a imagem resultante e, opcionalmente, um tempo limite para a versão. 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 o buildpack }valores e variáveis de ambiente. 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 de compilação in-line. Clique em Open Editor para gravar o arquivo de configuração da compilação no Console do Google Cloud usando a sintaxe YAML ou JSON. Clique em Concluído para salvar a configuração da compilação.

      No exemplo a seguir, os registros do arquivo de configuração de criação in-line ecoam "hello world":

       steps:
       - name: 'ubuntu'
         args: ['echo', 'hello world']
      
    • Substituições (opcional): se você tiver selecionado o arquivo de configuração da compilação como sua opção de configuração da compilação ou criado um arquivo de configuração de compilação in-line, será possível definir a substituição específica do gatilho Variáveis usando este campo. Também é possível receber 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.

      Para ver um exemplo de sintaxe de filtragem que pode ser aplicada aos seus gatilhos de webhook, consulte Como usar a CEL para filtrar eventos de compilação.

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

gcloud

Para criar um gatilho do webhook:

gcloud alpha builds triggers create webhook \
  --name=TRIGGER_NAME \
  --repo=PATH_TO_REPO \
  --secret=PATH_TO_SECRET \
  --substitutions=_SUB_ONE='$(body.message.test)',_SUB_TWO='$(body.message.output)' \
  --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:

  • TRIGGER_NAME é o nome do gatilho.
  • PATH_TO_REPO é o caminho para o repositório a que invocar uma compilação. Por exemplo, https://www.github.com/owner/repo.
  • PATH_TO_SECRET é o caminho para o secret, conforme armazenado no Secret Manager. Por exemplo, projects/my-project/secrets/my-secret/versions/2.
  • PATH_TO_INLINE_BUILD_CONFIG é o caminho para o arquivo de configuração de compilação in-line se você usar --inline-config.
  • TAG_NAME é o nome da tag se você quiser definir o gatilho para criação em uma tag.
  • PATH_TO_BUILD_CONFIG é o caminho para o arquivo de configuração de build, se você usar --build-config.
  • BRANCH_NAME é o nome da ramificação, caso você queira que o gatilho seja criado em uma ramificação.

(Opcional) Como receber uma chave de API

Você precisará de uma chave de API para autenticar o evento do webhook de entrada.

Para gerar uma chave de API:

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

    Abrir a página "Credenciais"

  2. Clique em Criar credenciais.

  3. Clique em Chave de API.

    Uma caixa de diálogo com a chave de API será criada. Anote a chave de API.

  4. Se quiser restringir a chave para aplicativos de produto, clique em Restringir chave para concluir outras etapas 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 Gerenciador de secrets à conta de serviço

O Cloud Build concede automaticamente o papel de Acessor do 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 Cloud.

    Abrir a página do IAM

  2. Anote a conta de serviço do Cloud Build à qual você quer conceder o papel.

  3. Abra a página do Gerenciador de secrets no Console do Cloud:

    Abrir a página "Gerenciador de secrets"

  4. Clique no nome do secret.

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

    1. Clique na guia Permissões no painel de informações à direita.

    2. Clique em Adicionar principal.

    3. Na seção Novo principal, adicione o e-mail associado à sua conta de serviço do Cloud Build.

    4. Na seção Selecionar um papel, selecione Gerenciador de secrets > Acessor de secrets do Gerenciador de secrets.

    5. Clique em Add.

Como usar a CEL para filtrar eventos de build

O Cloud Build usa a CEL com a variável build nos campos listados no recurso Build para acessar os campos associados ao evento de build, como o ID do gatilho, a lista de imagens ou os valores de substituição. Você pode usar a string filter para filtrar eventos de build no arquivo de configuração de build usando qualquer campo listado no recurso Build. Para encontrar a sintaxe exata associada ao seu campo, consulte o arquivo cloudbuild.proto.

Como filtrar por ID do gatilho

Para filtrar por ID de gatilho, especifique o valor do ID do gatilho no campo filter usando build.build_trigger_id, em que trigger-id é o ID do gatilho como uma string:

filter: build.build_trigger_id == trigger-id

Como filtrar por status

Para filtrar por status, especifique o status do build que você quer filtrar no campo filter usando build.status.

O exemplo a seguir mostra como filtrar eventos de build com um status SUCCESS usando o campo filter:

filter: build.status == Build.Status.SUCCESS

Também é possível filtrar builds com status variados. O exemplo a seguir mostra como filtrar eventos de build com um status SUCCESS, FAILURE ou TIMEOUT usando o campo filter:

filter: build.status in [Build.Status.SUCCESS, Build.Status.FAILURE, Build.Status.TIMEOUT]

Para ver valores de status adicionais pelos quais você pode filtrar, consulte Status na referência do recurso do Build.

Como filtrar por tag

Para filtrar por tag, especifique o valor da tag no campo filter usando build.tags, em que tag-name é o nome da tag:

filter: tag-name in build.tags

É possível filtrar com base no número de tags especificadas no evento de build usando size. No exemplo a seguir, o campo filter filtra eventos de build que têm exatamente duas tags especificadas, uma delas como v1:

filter: size(build.tags) == 2 && "v1" in build.tags

Como filtrar por imagens

Para filtrar por imagens, especifique o valor da imagem no campo filter usando build.images, em que image-name é o nome completo da imagem conforme listado no Container Registry, como gcr.io/example/image-one:

filter: image-name in build.images

No exemplo a seguir, o filter filtra eventos de build com gcr.io/example/image-one ou gcr.io/example/image-two especificados como nomes de imagem:

filter: "gcr.io/example/image-one" in build.images || "gcr.io/example/image-two" in build.images

Como filtrar por tempo

É possível filtrar eventos de build com base no tempo de criação, horário de início ou horário de término de um build especificando uma das seguintes opções no campo filter: build.create_time, build.start_time ou build.finish_time.

No exemplo a seguir, o campo filter usa timestamp para filtrar eventos de build com um horário de solicitação para criar o build em 20 de julho de 2020, às 6h:

filter: build.create_time == timestamp("2020-07-20:T06:00:00Z")

Também é possível filtrar eventos de build por comparações de tempo. No exemplo a seguir, o campo filter usa timestamp para filtrar eventos de versão com um horário de início entre 6 de julho de 2020, às 6h, e 30 de julho de 2020, às 6h.

filter: timestamp("2020-07-20:T06:00:00Z") >= build.start_time && build.start_time <= timestamp("2020-07-30:T06:00:00Z")

Para saber mais sobre como os fusos horários são expressos em CEL, consulte a definição de linguagem para fusos horários.

Para filtrar por duração de um build, use duration para comparar carimbos de data/hora. No exemplo a seguir, o campo filter usa duration para filtrar eventos de build com um build executado por pelo menos cinco minutos:

filter: build.finish_time - build.start_time >= duration("5m")

Como filtrar por substituição

É possível filtrar por substituição especificando a variável de substituição no campo filter usando build.substitutions. No exemplo a seguir, o campo filter lista versões que contêm a variável de substituição substitution-variable e verifica se o substitution-variable corresponde ao substitution-value especificado:

filter: build.substitutions[substitution-variable] == substitution-value

Em que:

  • substitution-variable é o nome da variável de substituição.
  • substitution-value é o nome do valor de substituição.

Também é possível filtrar por padrão os valores das variáveis de substituição. No exemplo a seguir, o campo filter lista os builds que têm o nome da ramificação master e os builds que têm o nome de repositório github.com/user/my-example-repo. As variáveis de substituição padrão BRANCH_NAME e REPO_NAME são transmitidas como chaves para o build.substitutions:

filter: build.substitutions["BRANCH_NAME"] == "master" && build.substitutions["REPO_NAME"] == "github.com/user/my-example-repo"

Se você quiser filtrar strings usando expressões regulares, use a função integrada matches. No exemplo abaixo, o campo filter filtra as criações com status FALHA ou TEMPO LIMITE e também tem uma variável de substituição de versão TAG_NAME com um valor correspondente à expressão regular v{DIGIT}.{DIGIT}.{3 DIGITS})

filter: build.status in [Build.Status.FAILURE, Build.Status.TIMEOUT] && build.substitutions["TAG_NAME"].matches("^v\\d{1}\\.\\d{1}\\.\\d{3}$")`

Para ver uma lista de valores de substituição padrão, consulte Como usar substituições padrão.

A seguir