Configurar notificações de problemas do GitHub

Experimental — githubissues

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 notificar você sobre atualizações do build enviar notificações para os canais desejados. Nesta página, explicamos como configurar notificações usando o notificador de problemas do GitHub.

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 notificações de problemas do GitHub

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

Para configurar problemas do GitHub:

1. Crie um token de acesso pessoal do GitHub:

   1. Acesse as configurações do GitHub para criar um novo token.

   2. Selecione o escopo repo.

      Observação :isso concede acesso total aos repositórios, inclusive aos privados.

   3. Clique em Gerar token.

2. Armazene o token do GitHub no Secret Manager:

   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 seu token do GitHub.

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

3. 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 token do GitHub.

   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.

4. 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. A guia Editar acesso vai aparecer.

   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.

5. Escreva um arquivo de configuração de modelo para descrever o formato que os problemas do GitHub criados devem ter:

   No exemplo de arquivo de configuração de modelo abaixo, os campos title e body usam variáveis de substituição do build:

   {
       "title": "Build {{.Build.BuildTriggerId}}: {{.Build.Status}}",
       "body": "[{{.Build.ProjectId}}] {{.Build.BuildTriggerId}} status: **{{.Build.Status}}**\n\n[View Logs]({{.Build.LogUrl}})"
   }
   

   Para ver o exemplo, consulte o arquivo de configuração de modelo para o notificador de problemas do GitHub.

   Campos adicionais podem ser definidos usando os parâmetros de corpo disponíveis no endpoint da endpoint de API para criar um problema.

6. Grave um arquivo de configuração do notificador para configurar o notificador de problemas do GitHub 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: GitHubIssuesNotifier
   metadata:
     name: example-githubissues-notifier
   spec:
     notification:
       filter: build.status == Build.Status.FAILURE
       template: 
         type: golang
         uri: gs://bucket_name/template-file-name
       delivery:
         githubToken:
           secretRef: github-token
         githubRepo: myuser/myrepo
     secrets:
     - name: github-token
       value: projects/project-id/secrets/secret-name/versions/latest
   

   Em que:

   • githubToken é a variável de configuração usada neste exemplo para fazer referência ao token do GitHub armazenado no Secret Manager. O nome da variável especificada aqui precisa corresponder ao campo name em secrets.
   • bucket-name é o nome do bucket.
   • template-file-name é o nome do arquivo de modelo.
   • myuser/myrepo é o nome do repositório em que os problemas serão criados.
   • project-id é o ID do seu projeto do Google Cloud.
   • secret-name é o nome do secret que contém o token do GitHub.

   Para conferir o exemplo, consulte o arquivo de configuração do notificador para o notificador de problemas do GitHub.

   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 upload do arquivo de configuração do notificador e do arquivo de modelo para 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 e do modelo do notificador para o bucket:

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

      Em que:

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

8. Implante o notificador no Cloud Run.

    gcloud run deploy service-name \
      --image=us-east1-docker.pkg.dev/gcb-release/cloud-build-notifiers/githubissues: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ções que você está criando.

   • config-path é o caminho para o arquivo de configuração do notificador relacionados aos problemas do GitHub. 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. Na próxima vez que você invocar um build, um problema será criado no repositório do GitHub definido se o build corresponder 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 ID do acionador, execute o seguinte comando: gcloud beta builds triggers describe trigger-name, em que trigger-name é o nome do gatilho. O comando listará os campos associados pelo seu acionador, incluindo o ID dele.

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 com 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 imagem:

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 no formato UTC "Zulu" RFC 3339, 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.