Automatizar builds em resposta a eventos do Pub/Sub

Com os gatilhos do Cloud Build Pub/Sub, é possível executar builds em resposta a eventos Google Cloud publicados no Pub/Sub. Você pode usar informações de um evento do Pub/Sub para parametrizar seu build e decidir se ele será executado em resposta ao evento. Os gatilhos do Pub/Sub podem ser configurados para detectar qualquer tópico do Pub/Sub.

Esta página explica como criar um gatilho do Pub/Sub para automatizar builds em resposta a eventos no Artifact Registry, no Container Registry (descontinuado) e no Cloud Storage.

Limitações

Os gatilhos do Pub/Sub do Cloud Build não são compatíveis com o uso do VPC Service Controls.

Antes de começar

  • Enable the Cloud Build API.

    Enable the API

  • Verifique se o código-fonte contém um arquivo de configuração do build ou um Dockerfile no repositório.

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

Como criar um gatilho de compilação que responde a eventos do Artifact Registry

É possível criar um gatilho do Pub/Sub que responde a eventos do Artifact Registry, como quando imagens são enviadas, excluídas ou tags são incluídas. Esta seção mostra como criar um gatilho do Pub/Sub que invoca um build quando uma nova tag é enviada para uma imagem existente. Se você não conhece o Artifact Registry, consulte a Visão geral do Artifact Registry.

Console

Para criar um gatilho que detecte uma nova tag enviada a uma imagem existente no Artifact Registry usando o console do Google Cloud:

  1. Acesse a página Gatilhos:

    Abrir a página Acionadores

  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: insira um nome para o gatilho.

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

      • 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 acionador precisa corresponder à região em que você criou o pool particular.
      • Se o arquivo de configuração do build associado ao acionador não especificar um pool particular, o Cloud Build vai usar o pool padrão para executar o build na mesma região do acionador.

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

    • Evento: selecione Mensagem do Pub/Sub como o evento para invocar o gatilho.

    • Assinatura: selecione o tópico do Pub/Sub que gostaria de assinar como o evento do gatilho. Você pode ver todos os tópicos atuais no projeto no menu suspenso.

    • Origem: selecione a origem a ser criada quando o gatilho do Pub/Sub for executado. É possível especificar 1ª geração ou 2ª geração como sua fonte.

      • 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. Os builds são executados sempre que uma mudança é 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.

      • 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 no seu repositório remoto, forneça o local do arquivo de configuração do build, o diretório Dockerfile 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.

    • Substituições (opcional): se você selecionou o arquivo de configuração do build como opção de configuração do build, é possível optar por definir variáveis de substituição específicas do gatilho usando este campo.

      No exemplo a seguir, queremos obter o nome da tag de imagem do payload e da ação associada ao evento gcr. Para tal, crie variáveis de substituição usando vinculações de payload.

      Especifique as seguintes variáveis e valores abaixo:

      Nome da variável Valor da variável
      _IMAGE_TAG $(body.message.data.tag)
      _ACTION $(body.message.data.action)

      body.message faz referência ao PubSubMessage publicado por editores e consumido por assinantes. Para ver mais exemplos do payload de notificação do Pub/Sub, consulte Exemplos de notificação.

    • Filtros (opcional): é possível criar filtros em um gatilho que determinam se o gatilho executará ou não um build em resposta ao payload de entrada especificando filtros em variáveis de substituição. A expressão de filtro precisa ser avaliada como true para que um build seja executado.

      Recomendamos usar a filtragem ao configurar gatilhos do Pub/Sub em tópicos com várias mensagens. Os filtros podem ser usados para controlar com precisão os builds que são executados em resposta às mensagens recebidas do Pub/Sub. Para saber os riscos associados à configuração de um gatilho sem filtros, consulte Riscos associados a um gatilho não filtrado.

      No exemplo a seguir, queremos que o gatilho execute um build se uma nova tag for enviada para uma imagem existente. Usamos operadores de condição de filtro para verificar se a variável _IMAGE_TAG corresponde a um nome de tag existente e se a variável _ACTION corresponde a INSERT para procurar dados recém-adicionados.

      Especifique o seguinte como seus filtros:

      • _IMAGE_TAG != ""
      • _ACTION == INSERT

      A sintaxe de filtragem nos gatilhos do Pub/Sub usa a Common Expression Language (CEL) para a avaliação de expressões. Para saber mais sobre CEL, consulte o repositório cel-spec.

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

gcloud

Para criar um gatilho que detecte uma nova tag enviada a uma imagem existente no Artifact Registry usando os comandos gcloud:

  1. Abra uma janela de terminal.

  2. Execute o comando gcloud para criar um gatilho de compilação no projeto. No exemplo abaixo, o gatilho está configurado para responder a builds com uma correspondência de tag prod e uma correspondência de ação INSERT com base no payload especificado, conforme definido pela variável de substituição, _IMAGE_TAG.

     gcloud builds triggers create pubsub \
   --region=REGION \
   --name=TRIGGER_NAME \
   --repository=projects/PROJECT_ID/locations/REGION/connections/CONNECTION_NAME/repositories/REPO_NAME \
   --topic=projects/PROJECT_ID/topics/TOPIC_NAME \
   --build-config=BUILD_CONFIG \ # or --inline-config=INLINE_BUILD_CONFIG
   --substitutions=\
     '_IMAGE_TAG_="$(body.message.data.tag)",' \
     '_ACTION="$(body.message.data.action)"' \
   --subscription-filter='_IMAGE_TAG != "" && _ACTION == "INSERT"' \
   --tag=TAG_NAME  # or --branch=BRANCH_NAME

Em que:

  • REGION é a região do acionador.
  • TRIGGER_NAME é o nome do gatilho.
  • PROJECT_ID é o ID do projeto do Cloud.
  • CONNECTION_NAME é o nome da conexão do host.
  • REPO_NAME é o nome do repositório;
  • TOPIC_NAME é o nome do tópico do Pub/Sub que você assinou.
  • BUILD_CONFIG é o caminho para seu arquivo de configuração do build.
  • INLINE_BUILD_CONFIG é o caminho para o arquivo de configuração do build inline.
  • TAG_NAME é o nome da tag caso você queira definir o gatilho para criar uma tag.
  • BRANCH_NAME é o nome da ramificação, caso você queira definir o gatilho para criar em uma ramificação.

Como criar um gatilho de compilação que responde a eventos do Container Registry

É possível criar um gatilho do Pub/Sub que responde a eventos do Container Registry, como quando imagens são enviadas, excluídas ou tags são incluídas. Esta seção mostra como criar um gatilho do Pub/Sub que invoca um build quando uma imagem corresponde a uma tag configurada por um filtro personalizado. Se você não estiver familiarizado com o Container Registry, consulte o Guia de início rápido do Container Registry para saber como enviar e receber imagens com tags.

Console

Para criar um gatilho que detecte um envio de imagem no Container Registry e faça a correspondência com base em um nome de tag usando o console do Google Cloud:

  1. Acesse a página Gatilhos:

    Abrir a página Acionadores

  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: insira um nome para o gatilho.

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

      • 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 acionador precisa corresponder à região em que você criou o pool particular.
      • Se o arquivo de configuração do build associado ao acionador não especificar um pool particular, o Cloud Build vai usar o pool padrão para executar o build na mesma região do acionador.

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

    • Evento: selecione Mensagem do Pub/Sub como o evento para invocar o gatilho.

    • Assinatura: selecione o tópico do Pub/Sub que gostaria de assinar como o evento do gatilho. Você pode ver todos os tópicos atuais no projeto no menu suspenso.

    • Origem: selecione a origem a ser criada quando o gatilho do Pub/Sub for executado. É possível especificar 1ª geração ou 2ª geração como sua fonte.

      • 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. Os builds são executados sempre que uma mudança é 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.

      • 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 no seu repositório remoto, forneça o local do arquivo de configuração do build, o diretório Dockerfile 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.

    • Substituições (opcional): se você selecionou o arquivo de configuração do build como opção de configuração do build, é possível optar por definir variáveis de substituição específicas do gatilho usando este campo.

      No exemplo a seguir, queremos obter o nome da tag de imagem do payload e da ação associada ao evento gcr. Para tal, crie variáveis de substituição usando vinculações de payload.

      Especifique as seguintes variáveis e valores abaixo:

      Nome da variável Valor da variável
      _IMAGE_TAG $(body.message.data.tag)
      _ACTION $(body.message.data.action)

      body.message faz referência ao PubSubMessage publicado por editores e consumido por assinantes. Para ver mais exemplos do payload de notificação do Pub/Sub, consulte Exemplos de notificação.

    • Filtros (opcional): é possível criar filtros em um gatilho que determinam se o gatilho executará ou não um build em resposta ao payload de entrada especificando filtros em variáveis de substituição. A expressão de filtro precisa ser avaliada como true para que um build seja executado.

      Recomendamos usar a filtragem ao configurar gatilhos do Pub/Sub em tópicos com várias mensagens. Os filtros podem ser usados para controlar com precisão os builds que são executados em resposta às mensagens recebidas do Pub/Sub. Para saber os riscos associados à configuração de um gatilho sem filtros, consulte Riscos associados a um gatilho não filtrado.

      No exemplo a seguir, queremos que o gatilho execute um build se o nome da variável de tag _IMAGE_TAG corresponder a um nome de tag específico, como prod. Você pode especificar o operador da condição de filtro como "==" para correspondência exata. Também é possível verificar a ação associada ao seu evento gcr. Por exemplo, talvez você queira especificar _ACTION como INSERT para procurar dados recém-adicionados.

      Especifique o seguinte como seus filtros:

      • _IMAGE_TAG.matches(prod)
      • _ACTION.matches(INSERT)

      A sintaxe de filtragem nos gatilhos do Pub/Sub usa a Common Expression Language (CEL) para a avaliação de expressões. Para saber mais sobre CEL, consulte o repositório cel-spec. Para ver mais exemplos de sintaxe de filtragem que podem ser aplicados aos seus gatilhos do Pub/Sub, consulte Como filtrar builds.

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

gcloud

Como criar um gatilho de compilação que responde a eventos do Cloud Storage

É possível criar um gatilho do Pub/Sub que responde a eventos do Cloud Storage, como quando um novo binário é enviado para um bucket de armazenamento atual. Esta seção mostra como criar um gatilho do Pub/Sub que responde com um build ao implantar um novo binário em um bucket enviado. Se você não estiver familiarizado com o Cloud Storage, consulte os Guias de início rápido.

Console

Para criar um gatilho que detecte eventos do Cloud Storage usando o console do Google Cloud:

  1. Acesse a página Gatilhos:

    Abrir a página Acionadores

  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: insira um nome para o gatilho.

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

      • 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 acionador precisa corresponder à região em que você criou o pool particular.
      • Se o arquivo de configuração do build associado ao acionador não especificar um pool particular, o Cloud Build vai usar o pool padrão para executar o build na mesma região do acionador.

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

    • Evento: selecione Mensagem do Pub/Sub como o evento para invocar o gatilho.

    • Assinatura: selecione o tópico do Pub/Sub que gostaria de assinar como o evento do gatilho. Você pode ver todos os tópicos atuais no projeto no menu suspenso.

    • Origem: selecione a origem a ser criada quando o gatilho do Pub/Sub for executado. É possível especificar 1ª geração ou 2ª geração como sua fonte.

      • 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. Os builds são executados sempre que uma mudança é 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.

      • 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 no seu repositório remoto, forneça o local do arquivo de configuração do build, o diretório Dockerfile 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.

    • Substituições (opcional): se você selecionou o arquivo de configuração do build como opção de configuração do build, é possível optar por definir variáveis de substituição específicas do gatilho usando este campo.

      Neste exemplo, queremos observar a implantação de um novo binário quando ele for enviado para um bucket. Para obter esses dados, podemos criar variáveis de substituição usando vinculações de payload.

      Especifique as seguintes variáveis e valores abaixo:

      Nome da variável Valor da variável
      _EVENT_TYPE $(body.message.attributes.eventType)
      _BUCKET_ID $(body.message.attributes.bucketId)
      _OBJECT_ID $(body.message.attributes.objectId)

      body.message faz referência ao PubSubMessage publicado por editores e consumido por assinantes. Para ver mais exemplos do payload de notificação do Pub/Sub, consulte Exemplos de notificação.

    • Filtros (opcional): é possível criar filtros em um gatilho que determinam se o gatilho executará ou não um build em resposta ao payload de entrada especificando filtros em variáveis de substituição. A expressão de filtro precisa ser avaliada como true para que um build seja executado.

      Recomendamos usar a filtragem ao configurar gatilhos do Pub/Sub em tópicos com várias mensagens. Os filtros podem ser usados para controlar com precisão os builds que são executados em resposta às mensagens recebidas do Pub/Sub. Para saber os riscos associados à configuração de um gatilho sem filtros, consulte Riscos associados a um gatilho não filtrado.

      Como queremos que o gatilho execute um build se o novo binário tiver sido implantado em um bucket específico, podemos usar o operador "==" para verificar correspondências exatas. Você também pode usar a palavra-chave "corresponde" se quiser fazer a correspondência por expressão regular.

      Especifique o seguinte como seus filtros:

      • _EVENT_TYPE == OBJECT_FINALIZE
      • _OBJECT_ID corresponde ^<object-id>$
      • _BUCKET_ID corresponde ^<bucket-id>$
  1. Clique em Criar para criar seu gatilho de compilação.
    2. .

gcloud

Riscos associados a um gatilho não filtrado

Se você não tiver configurado filtros no gatilho do Pub/Sub, ele poderá acabar invocando um número infinito de builds se o gatilho modificar um artefato ou objeto que publica acidentalmente uma nova mensagem no tópico que está detectando. Por exemplo, seu gatilho poderá invocar um número infinito de builds se o gatilho:

  • Aponta para um tópico gcr.
  • Cria qualquer imagem ou tag em gcr.
  • Aponta para um tópico gcs de um objeto específico no bucket e modifica esse objeto.

Se você encontrar um loop infinito, poderá excluir o gatilho ou atualizá-lo para apontar para um tópico separado para evitar cobranças adicionais por cada build que você invocar.

A seguir