Configurar as notificações do Google Chat

Experimental — googlechat

Esse recurso está sujeito aos "Termos de ofertas pré-GA" na seção "Termos de Serviço gerais" dos Termos específicos de serviço. Os recursos pré-GA estão disponíveis "no estado em que se encontram" e podem ter suporte limitado. Para mais informações, consulte as descrições da fase de lançamento.

O Cloud Build pode notificá-lo sobre atualizações de criação enviando notificações para os canais pretendidos, como o Slack ou seu servidor SMTP. Esta página explica como configurar as notificações usando o notificador do Google Chat.

Antes de começar

• Enable the Cloud Build, Compute Engine, Cloud Run, Pub/Sub, and Secret Manager APIs.

  Enable the APIs

• Instale o Google Cloud CLI.

Como configurar as notificações do Google Chat

A seção a seguir explica como configurar manualmente as notificações do Google Chat usando o notificador do Google Chat. Se você quiser automatizar a configuração, consulte Como automatizar a configuração de notificações.

Para configurar as notificações do Google Chat:

1. Criar um espaço no Google Chat.

2. No espaço criado, crie um webhook de entrada para postar mensagens do Cloud Build no Google Chat. Seu URL será semelhante a este:

   https://chat.googleapis.com/v1/spaces/...
   

3. Armazene o URL do webhook de entrada no Gerenciador de secrets:

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

      Abrir a página "Gerenciador de secrets"

   2. Clique em Criar secret.

   3. Insira um nome para o secret.

   4. Em Valor do secret, adicione o URL de webhook de entrada do seu espaço do Google Chat.

   5. Para salvar o secret, clique em Criar secret.

4. Embora a conta de serviço do Cloud Run possa ter o papel de Editor para o projeto, o papel de Editor não é suficiente para acessar o secret no Secret Manager. Você precisará conceder acesso ao secret à sua conta de serviço do Cloud Run:

   1. Acesse a página "IAM" no Console do Google Cloud.

      Abrir a página do IAM

   2. Localize a conta de serviço padrão do Compute Engine associada ao seu projeto:

      Sua conta de serviço padrão do Compute Engine será semelhante a esta:

      [e-mail]
      

      Anote a conta de serviço padrão do Compute Engine.

      Observação: por padrão, o Cloud Run executa as imagens do notificador com a conta de serviço padrão do Compute Engine e a utiliza para buscar o secret. Para mais informações sobre contas de serviço em ambiente de execução, consulte Conta de serviço em ambiente de execução.

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

      Abrir a página "Gerenciador de secrets"

   4. Clique no nome do secret que contém o secret do webhook do Google Chat.

   5. Na guia Permissões, clique em Adicionar membro.

   6. Adicione a conta de serviço padrão do Compute Engine associada ao projeto como membro.

   7. Selecione como papel a permissão Acessador de secrets do Gerenciador de secrets.

   8. Clique em Salvar.

5. Conceda permissão à conta de serviço do Cloud Run para leitura Buckets do Cloud Storage:

   1. Acesse a página "IAM" no Console do Google Cloud.

      Abrir a página do IAM

   2. Localize a conta de serviço padrão do Compute Engine associada ao seu projeto:

      Sua conta de serviço padrão do Compute Engine será semelhante a esta:

      [e-mail]
      

   3. Clique no ícone de lápis na linha que contém sua conta de serviço padrão do Compute Engine. Você verá a guia Editar acesso.

   4. Clique em Adicionar outro papel.

   5. Adicione o seguinte papel:

      • Leitor de objetos do Storage
      Observação: se você quiser conceder permissões no nível do bucket e não no nível do projeto, adicione o papel Proprietário do objeto legado do Storage quando você criar um bucket. Para saber mais, consulte Diferença entre papéis do projeto e papéis no nível do bucket.

   6. Clique em Salvar.

6. Grave um arquivo de configuração do notificador para configurar seu notificador do Google Chat e filtrar eventos de build:

   No exemplo de arquivo de configuração do notificador de exemplo, o campo filter usa Common Expression Language com a variável disponível, build, para filtrar os eventos de build com um status SUCCESS:

   apiVersion: cloud-build-notifiers/v1
   kind: GoogleChatNotifier
   metadata:
     name: example-googlechat-notifier
   spec:
     notification:
       filter: build.status == Build.Status.SUCCESS
       delivery:
         webhookUrl:
           secretRef: webhook-url
     secrets:
     - name: webhook-url
       value: projects/project-id/secrets/secret-name/versions/latest
   

   Em que:

   • webhook-url é a variável de configuração usada neste exemplo para faça referência ao caminho do URL do webhook do Google Chat armazenado no Secret Manager. O nome da variável especificada aqui precisa corresponder ao campo name em secrets.
   • project-id é o ID do seu projeto do Google Cloud.
   • secret-name é o nome do secret que contém o URL do webhook do Google Chat.

   Para ver o exemplo, consulte o arquivo de configuração do notificador do Google Chat notificador.

   Para ver outros campos que podem ser filtrados, consulte o recurso Build. Para ver mais exemplos de filtragem, consulte Como usar a CEL para filtrar eventos do build.

7. Faça o upload do arquivo de configuração do notificador em um bucket do Cloud Storage:

   1. Se você não tiver um bucket do Cloud Storage, execute o seguinte comando para criar um bucket, em que bucket-name é o nome que você quer dar ao bucket, sujeito aos requisitos de nomenclatura.

      gcloud storage buckets create gs://bucket-name/
      

   2. Faça o upload do arquivo de configuração do notificador para o bucket:

      gcloud storage cp config-file-name gs://bucket-name/config-file-name
      

      Onde:

      • bucket-name é o nome do bucket.
      • config-file-name é o nome do seu arquivo de configuração.

8. Implante o notificador no Cloud Run.

    gcloud run deploy service-name \
      --image=us-east1-docker.pkg.dev/gcb-release/cloud-build-notifiers/googlechat:latest \
      --no-allow-unauthenticated \
      --update-env-vars=CONFIG_PATH=config-path,PROJECT_ID=project-id
   

   Onde:

   • service-name é o nome do serviço do Cloud Run em que você está implantando a imagem;

     Observação: service-name faz referência ao novo serviço de notificação que você estão criando.

   • config-path é o caminho para o arquivo de configuração do notificador do Google Chat. notificador: gs://bucket-name/config-file-name.

   • project-id é o ID do seu projeto do Google Cloud.

   O comando gcloud run deploy extrai a versão mais recente da imagem hospedada do Registro de artefatos de propriedade do Cloud Build. O Cloud Build oferece suporte a imagens do notificador por nove meses. Após nove meses, o Cloud Build exclui a versão da imagem. Se quiser usar uma versão de imagem anterior, você precisará especificar a versão semântica completa da tag de imagem no atributo image do seu comando gcloud run deploy. Versões e tags de imagem anteriores podem ser encontradas no Artifact Registry.

   Observação: ao executar esse comando, talvez seja necessário especificar outros argumentos, como --region ou --platform. Para saber mais sobre parâmetros que podem ser transmitidos ao comando gcloud run deploy, consulte Como implantar no Cloud Run. Se você não conseguir implantar o notificador usando esse comando, consulte o guia de solução de problemas do Cloud Run para saber como resolver erros de implantação.

9. Conceda permissões do Pub/Sub para criar tokens de autenticação no seu projeto:

    gcloud projects add-iam-policy-binding project-id \
      --member=serviceAccount:[e-mail] \
      --role=roles/iam.serviceAccountTokenCreator
   

   Em que:

   • project-id é o ID do seu projeto do Google Cloud.
   • project-number é o número do projeto do Google Cloud.
   .
   Observação: se a conta de serviço do Pub/Sub não existir seu projeto, consulte Criar e usar assinaturas.

10. Crie uma conta de serviço para representar sua identidade de assinatura do Pub/Sub:

    gcloud iam service-accounts create cloud-run-pubsub-invoker \
      --display-name "Cloud Run Pub/Sub Invoker"
    

    Você pode usar cloud-run-pubsub-invoker ou um nome exclusivo no seu projeto do Google Cloud.

11. Conceda à conta de serviço cloud-run-pubsub-invoker a permissão Invoker do Cloud Run:

    gcloud run services add-iam-policy-binding service-name \
       --member=serviceAccount:[e-mail] \
       --role=roles/run.invoker
    

    Em que:

    • service-name é o nome do serviço do Cloud Run em que você está implantando a imagem;
    • project-id é o ID do seu projeto do Google Cloud.

12. Crie o tópico cloud-builds para receber mensagens de atualização da build para seu notificador:

    gcloud pubsub topics create cloud-builds
    

13. Crie um assinante de push do Pub/Sub para seu notificador:

     gcloud pubsub subscriptions create subscriber-id \
       --topic=cloud-builds \
       --push-endpoint=service-url \
       --push-auth-service-account=[e-mail]
    

    Em que:

    • subscriber-id é o nome que você quer dar à sua assinatura.
    • service-url é o URL gerado pelo Cloud Run para o novo serviço.
    • project-id é o ID do seu projeto do Google Cloud.

Agora as notificações do seu projeto do Cloud Build estão configuradas. O próximo sempre que invocar um build, você receberá uma notificação no Google Chat se ele corresponde ao filtro que você configurou.

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. Use a string filter para filtrar eventos de build no arquivo de configuração do build usando qualquer campo listado no recurso Build. Para encontrar a sintaxe exata associada ao seu campo, consulte a cloudbuild.proto .

Como filtrar por ID do acionador

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

Observação :o ID não é o nome do seu acionador. Para receber o ID do acionador, execute o seguinte comando: gcloud beta builds triggers describe trigger-name, em que trigger-name é o nome do acionador. O comando lista os campos associados ao acionador, incluindo o 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 sua imagem no campo filter usando build.images, em que image-name é o nome completo da imagem conforme listado no Artifact Registry, como us-east1-docker.pkg.dev/my-project/docker-repo/image-one:

filter: image-name in build.images

No exemplo a seguir, o filter filtra eventos de build que tenham us-east1-docker.pkg.dev/my-project/docker-repo/image-one ou us-east1-docker.pkg.dev/my-project/docker-repo/image-two especificado como nomes de imagens:

filter: "us-east1-docker.pkg.dev/my-project/docker-repo/image-one" in build.images || "us-east1-docker.pkg.dev/my-project/docker-repo/image-one" 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")

Observação :os carimbos de data/hora estão em RFC 3339 UTC "Zulu" com resolução de nanossegundos e até nove dígitos fracionários.

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

• Saiba mais sobre os notificadores do Cloud Build.
• Saiba como se inscrever para criar notificações.
• Saiba como gravar um arquivo de configuração da compilação do Cloud Build.