Configurar notificações do Slack

O Cloud Build pode notificar você sobre atualizações de build enviando notificações para os canais selecionados, como o Slack ou seu servidor SMTP. Nesta página, explicamos como configurar notificações usando o notificador do Slack.

Antes de começar

• Ative as APIs Cloud Build, Compute Engine, Cloud Run, Pub/Sub e Secret Manager, se alguma delas ainda não estiver ativada.

  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 com o papel de Proprietário (roles/owner). Caso contrário, é possível receber essa permissão com o papel de Administrador do Service Usage (roles/serviceusage.serviceUsageAdmin). Saiba como conceder papéis.

  Ativar as APIs

• Instale a CLI do Google Cloud.

Como configurar notificações do Slack

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

Para configurar as notificações do Slack:

1. Crie um app Slack para seu espaço de trabalho do Slack.

2. Ative webhooks de entrada para postar mensagens no Slack pelo Cloud Build.

3. Navegue até seu aplicativo do Slack para localizar o URL do webhook de entrada. O URL será semelhante ao seguinte:

   http://hooks.slack.com/services/...
   

4. Armazene o URL do webhook de entrada no Secret Manager:

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

      Abra a página do Secret Manager

   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 aplicativo Slack.

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

5. Embora sua conta de serviço do Cloud Run possa ter o papel de Editor no projeto, ele não é suficiente para acessar o secret no Secret Manager. Para dar à conta de serviço do Cloud Run acesso ao seu secret, faça o seguinte:

   1. Acesse a página do IAM no console 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:

      project-number-compute@developer.gserviceaccount.com
      

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

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

      Abra a página do Secret Manager

   4. Clique no nome do secret que contém o secret do seu app Slack.

   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 a permissão Acessador de secrets do Secret Manager como a função.

   8. Clique em Salvar.

6. Conceda à conta de serviço do Cloud Run permissão para ler buckets do Cloud Storage:

   1. Acesse a página do IAM no console 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:

      project-number-compute@developer.gserviceaccount.com
      

   3. Clique no ícone de lápis na linha que contém sua conta de serviço padrão do Compute Engine. A guia acesso de edição vai aparecer.

   4. Clique em Adicionar outro papel.

   5. Adicione o seguinte papel:

      • Leitor de objetos do Storage

   6. Clique em Salvar.

7. Grave um arquivo de configuração do notificador para configurar seu notificador do Slack 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: SlackNotifier
   metadata:
     name: example-slack-notifier
   spec:
     notification:
       filter: build.status == Build.Status.SUCCESS
       params:
         buildStatus: $(build.status)
       delivery:
         webhookUrl:
           secretRef: WEBHOOK_URL_SECRET_NAME
       template:
         type: golang
         uri: gs://BUCKET_NAME/slack.json
     secrets:
     - name: WEBHOOK_URL_SECRET_NAME
       value: projects/PROJECT_ID/secrets/SECRET_NAME/versions/latest
   

   Em que:

   • buildStatus é um parâmetro definido pelo usuário. Esse parâmetro assume o valor de $(build.status), o status do build.
   • WEBHOOK_URL_SECRET_NAME é o nome do secret do Secret Manager que contém o caminho do URL do webhook do Slack. O nome da variável especificado aqui precisa corresponder ao campo name em secrets neste YAML.
   • BUCKET_NAME é o nome do bucket.
   • PROJECT_ID é o ID do projeto do Google Cloud .
   • SECRET_NAME é o nome do secret que contém o URL do webhook do Slack.

   • O campo uri faz referência ao arquivo slack.json. Esse arquivo contém um modelo JSON hospedado no Cloud Storage e representa sua mensagem de notificação para o espaço do Slack.

     O arquivo de modelo JSON usa os recursos do blockkit do Slack. Para ver um exemplo de arquivo de modelo, consulte o arquivo slack.json no repositório cloud-build-notifiers.

   Para ver o exemplo, consulte o arquivo de configuração do notificado para o notificador do Slack.

   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.

8. 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.

9. Implante o notificador no Cloud Run.

    gcloud run deploy SERVICE_NAME \
      --image=us-east1-docker.pkg.dev/gcb-release/cloud-build-notifiers/slack: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;
   • CONFIG_PATH é o caminho para o arquivo de configuração do notificador do notificador do Slack, gs://BUCKET_NAME/CONFIG_FILE_NAME.
   • PROJECT_ID é o ID do 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.

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

    gcloud iam service-accounts create SUB_IDENTITY_SERVICE_ACCOUNT \
      --display-name "SUB_IDENTITY_SERVICE_ACCOUNT_DISPLAY_NAME"
    

    Em que:

    • SUB_IDENTITY_SERVICE_ACCOUNT é um nome para a conta de serviço.

    • SUB_IDENTITY_SERVICE_ACCOUNT_DISPLAY_NAME é um nome de exibição para a conta de serviço.

11. Conceda à conta de serviço de identidade de assinatura do Pub/Sub as permissões necessárias para criar tokens de autenticação no seu projetoGoogle Cloud .

    gcloud iam service-accounts add-iam-policy-binding \
        SUB_IDENTITY_SERVICE_ACCOUNT@PROJECT_ID.iiam.gserviceaccount.com \
        --member=serviceAccount:service-PROJECT_NUMBER@gcp-sa-pubsub.iam.gserviceaccount.com \
        --role=roles/iam.serviceAccountTokenCreator
    

    Em que:

    • PROJECT_ID é o ID do projeto do Google Cloud .

    • PROJECT_NUMBER é o número do projeto do Google Cloud .

12. Conceda à conta de serviço SUB_IDENTITY_SERVICE_ACCOUNT o papel Invoker do Cloud Run:

    gcloud run services add-iam-policy-binding SERVICE_NAME \
       --member=serviceAccount:SUB_IDENTITY_SERVICE_ACCOUNT@PROJECT_ID.iam.gserviceaccount.com \
       --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 projeto do Google Cloud .

13. Crie o tópico cloud-builds para receber mensagens de atualização de build do seu notifier:

    gcloud pubsub topics create cloud-builds
    

    Também é possível definir um nome de tópico personalizado no arquivo de configuração do build para que as mensagens sejam enviadas ao tópico personalizado. Nesse caso, você criaria um tópico com o mesmo nome personalizado:

    gcloud pubsub topics create topic-name
    

    Para mais informações, consulte Tópicos do Pub/Sub para notificações de build.

14. 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=SUB_IDENTITY_SERVICE_ACCOUNT@PROJECT_ID.iam.gserviceaccount.com

Em que: + SUBSCRIBER_ID é o nome que você quer dar à assinatura. + SERVICE_URL é o URL gerado pelo Cloud Run para seu novo serviço. + PROJECT_ID é o ID do projeto do Google Cloud .

Note: By default, [subscriptions expire after 31 days of inactivity](/pubsub/docs/subscription-overview#lifecycle).
You can adjust or disable the expiration period by including the
[`--expiration-period` flag](/sdk/gcloud/reference/pubsub/subscriptions/create#--expiration-period)
when creating the subscription.

Agora as notificações do seu projeto do Cloud Build estão configuradas. Da próxima vez que você invocar um build, você receberá uma notificação no Slack caso o build corresponda ao filtro que você configurou.

Como usar a CEL para filtrar eventos do 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 o arquivo 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

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 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 têm us-east1-docker.pkg.dev/my-project/docker-repo/image-one ou us-east1-docker.pkg.dev/my-project/docker-repo/image-two especificados 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")

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 escrever um arquivo de configuração do build do Cloud Build.