Como filtrar builds em notificações

Para notificar você sobre atualizações no status do build, o Cloud Build envia notificações para os canais desejados, como o Slack ou o servidor SMTP. Use a Common Expression Language (CEL), uma linguagem de código aberto que avalia expressões, para filtrar os eventos de build sobre os quais você quer receber notificações. Para saber mais sobre notificadores, consulte cloud-build-notifiers.

Esta página explica como filtrar eventos de build usando CEL.

Suporte a CEL na filtragem de eventos de build.

No momento, o Cloud Build oferece suporte a CEL na string filter nos arquivos de configuração do notificador. No arquivo de configuração do notificador, é possível especificar a string filter para filtrar eventos de build. O exemplo abaixo mostra um arquivo de configuração de notificador que usa a string filter para filtrar eventos de build com um status SUCCESS:


    apiVersion: cloud-build-notifiers/v1
    kind: my-notifier
    metadata:
      name: my-notifier-one
    spec:
      notification:
        filter: build.status == Build.Status.SUCCESS
        delivery:
          url: https://notifier.com/one
          

Para ver um exemplo completo de um arquivo de configuração do notificador, consulte os exemplos de arquivos do notificador do Slack, SMTP ou HTTP.

Exemplos de filtragem

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 notificador 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 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"

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

A seguir