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 do 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 têm suporte quando O VPC Service Controls é usado.

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 acionador que detecte uma nova tag enviada a um imagem atual 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 gatilho.

      • Se o arquivo de configuração do build associado ao gatilho especificar um pool particular, o Cloud Build usa esse pool 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): 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. 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.

      • 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 seu arquivo de configuração de build no Console do Google Cloud usando 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 gatilho.
  • 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 gatilho.

      • Se o arquivo de configuração do build associado ao gatilho especificar um pool particular, o Cloud Build usa esse pool 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 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): 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. 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.

      • 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 seu arquivo de configuração de build no Console do Google Cloud usando 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 gatilho especificar um pool particular, o Cloud Build usa esse pool 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): 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 é 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. 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.

      • 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