Esta página foi traduzida pela API Cloud Translation.

Configure as notificações de problemas do GitHub

O Cloud Build pode enviar-lhe notificações de atualizações de compilação para canais selecionados. Esta página explica como configurar as notificações através do 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 a CLI do Google Cloud.

Configurar notificações de problemas do GitHub

A secção seguinte explica como pode configurar manualmente as notificações de problemas do GitHub através do notificador de problemas do GitHub. Se, em alternativa, quiser automatizar a configuração, consulte o artigo Automatizar a configuração para notificações.

Para configurar o GitHub Issues:

Crie um token de acesso pessoal do GitHub:
1. Aceda às definições do GitHub para criar um novo token.
2. Selecione o âmbito repo.
  
  Nota: isto concede acesso total aos repositórios, incluindo repositórios privados.
3. Clique em Gerar token
Armazene o seu token do GitHub no Secret Manager:
1. Abra a página Secret Manager na Google Cloud consola:
  
  Abra a página Secret Manager
2. Clique em Criar segredo.
3. Introduza um nome para o segredo.
4. Em Valor secreto, adicione o seu token do GitHub.
5. Para guardar o segredo, clique em Criar segredo.
Embora a sua conta de serviço do Cloud Run possa ter a função de Editor para o seu projeto, a função de Editor não é suficiente para aceder ao seu segredo no Secret Manager. Para conceder à conta de serviço do Cloud Run acesso ao seu segredo, faça o seguinte:
1. Aceda à página IAM na Google Cloud consola:
  
  Abra a página IAM
2. Localize a conta de serviço predefinida do Compute Engine associada ao seu projeto:
  
  A sua conta de serviço predefinida do Compute Engine vai ser semelhante à seguinte:
```
project-number-compute@developer.gserviceaccount.com
```
  Tome nota da conta de serviço predefinida do Compute Engine.
  
  Nota: por predefinição, o Cloud Run executa as suas imagens do notificador com a conta de serviço predefinida do Compute Engine e usa-a para obter o seu segredo. Para saber mais sobre as contas de serviço do Runtime, consulte o artigo Conta de serviço do Runtime.
3. Abra a página Secret Manager na Google Cloud consola:
  
  Abra a página Secret Manager
4. Clique no nome secreto que contém o segredo do seu token do GitHub.
5. No separador Permissões, clique em Adicionar membro.
6. Adicione a conta de serviço predefinida do Compute Engine associada ao seu projeto como membro.
7. Selecione a autorização Secret Manager Secret Accessor como função.
8. Clique em Guardar.
Conceda à sua conta de serviço do Cloud Run autorização para ler a partir de contentores do Cloud Storage:
1. Aceda à página IAM na Google Cloud consola:
  
  Abra a página IAM
2. Localize a conta de serviço predefinida do Compute Engine associada ao seu projeto:
  
  A sua conta de serviço predefinida do Compute Engine vai ser semelhante à seguinte:
```
project-number-compute@developer.gserviceaccount.com
```
3. Clique no ícone de lápis na linha que contém a conta de serviço predefinida do Compute Engine. É apresentado o separador Acesso de edição.
4. Clique em Adicionar outra função.
5. Adicione a seguinte função:
  - Storage Object Viewer
  Nota: se quiser conceder autorizações ao nível do contentor em vez do nível do projeto, adicione a função Proprietário do objeto antigo de armazenamento ao seu contentor quando criar um. Para saber mais, consulte o artigo Atribuir funções ao nível do projeto, do contentor ou da pasta gerida.
6. Clique em Guardar.
Escreva um ficheiro de configuração de modelo para descrever o formato que os problemas do GitHub criados devem ter:

No ficheiro de configuração do modelo de exemplo seguinte, os campos title e body usam variáveis de substituição da compilação:
```
{
    "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 ficheiro de configuração do modelo para o notificador de problemas do GitHub.

Pode definir campos adicionais a partir dos parâmetros do corpo disponíveis no ponto final da API GitHub para criar um problema.
Escreva um ficheiro de configuração do notificador para configurar o notificador de problemas do GitHub e filtre por eventos de compilação:

No ficheiro de configuração do notificador do exemplo seguinte, o campo filter usa a linguagem de expressão comum com a variável disponível, build, para filtrar eventos de compilação com um estado 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
```
Onde:
- 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 que especificar aqui deve corresponder ao campo name em secrets.
- bucket-name é o nome do seu contentor.
- template-file-name é o nome do ficheiro de modelo.
- myuser/myrepo é o nome do repositório no qual os problemas vão ser criados.
- project-id é o ID do seu Google Cloud projeto.
- secret-name é o nome do seu segredo que contém o seu token do GitHub.
Para ver o exemplo, consulte o ficheiro de configuração do notificador para o notificador de problemas do GitHub.

Para ver campos adicionais pelos quais pode filtrar, consulte o recurso Build. Para ver exemplos de filtragem adicionais, consulte o artigo Usar o IEC para filtrar eventos de compilação.
Carregue o ficheiro de configuração do notificador e o ficheiro de modelo para um contentor do Cloud Storage:
1. Se não tiver um contentor do Cloud Storage, execute o seguinte comando para criar um contentor, em que bucket-name é o nome que quer dar ao seu contentor, sujeito aos requisitos de nomenclatura.
```
gcloud storage buckets create gs://bucket-name/
```
2. Carregue o ficheiro de configuração do notificador e o ficheiro de modelo para o seu contentor:
```
gcloud storage cp config-file-name gs://bucket-name/config-file-name

gcloud storage cp template-file-name gs://bucket-name/template-file-name
```
  Onde:
  - bucket-name é o nome do seu contentor.
  - config-file-name é o nome do ficheiro de configuração.
  - template-file-name é o nome do ficheiro de modelo.
Implemente o seu serviço de notificação 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 para o qual está a implementar a imagem.
- config-path é o caminho para o ficheiro de configuração do notificador do Slack, gs://bucket-name/config-file-name.
- project-id é o ID do seu Google Cloud projeto.
O comando gcloud run deploy extrai a versão mais recente da imagem alojada do Artifact Registry pertencente ao Cloud Build. O Cloud Build suporta imagens de notificador durante nove meses. Após nove meses, o Cloud Build elimina a versão da imagem. Se quiser usar uma versão anterior da imagem, tem de especificar a versão semântica completa da etiqueta de imagem no atributo image do comando gcloud run deploy. Pode encontrar as versões e as etiquetas de imagens anteriores no Artifact Registry.

Nota: ao executar este comando, pode ser-lhe pedido que especifique argumentos adicionais, como --region ou --platform. Para saber mais acerca dos parâmetros que pode transmitir para o comando gcloud run deploy, consulte o artigo Implementação no Cloud Run. Se não conseguir implementar o seu notificador através deste comando, consulte o guia de resolução de problemas do Cloud Run para ver soluções sobre como resolver erros de implementação.
Conceda autorizações do Pub/Sub para criar tokens de autenticação no seu Google Cloud projeto:
```
 gcloud projects add-iam-policy-binding project-id \
   --member=serviceAccount:service-project-number@gcp-sa-pubsub.iam.gserviceaccount.com \
   --role=roles/iam.serviceAccountTokenCreator
```
Onde:
- project-id é o ID do seu Google Cloud projeto.
- project-number é o número do seu Google Cloud projeto.
Nota: se a conta de serviço do Pub/Sub não existir no seu projeto, consulte o artigo Crie e use subscrições.
Crie uma conta de serviço para representar a identidade da sua subscrição do Pub/Sub:
```
gcloud iam service-accounts create cloud-run-pubsub-invoker \
  --display-name "Cloud Run Pub/Sub Invoker"
```
Pode usar cloud-run-pubsub-invoker ou usar um nome único no seu projeto Google Cloud .
Conceda à conta de serviço cloud-run-pubsub-invoker a autorização Invoker do Cloud Run:
```
gcloud run services add-iam-policy-binding service-name \
   --member=serviceAccount:cloud-run-pubsub-invoker@project-id.iam.gserviceaccount.com \
   --role=roles/run.invoker
```
Onde:
- service-name é o nome do serviço do Cloud Run para o qual está a implementar a imagem.
- project-id é o ID do seu Google Cloud projeto.
Crie o tópico cloud-builds para receber mensagens de atualização de compilação para o seu notificador:
```
gcloud pubsub topics create cloud-builds
```
Também pode definir um nome de tópico personalizado no ficheiro de configuração de compilação para que as mensagens sejam enviadas para o tópico personalizado. Neste caso, criaria um tópico com o mesmo nome de tópico personalizado:
```
gcloud pubsub topics create topic-name
```
Para mais informações, consulte o artigo Tópicos do Pub/Sub para notificações de compilação.
Crie um subscritor de envio do Pub/Sub para o seu notificador:
```
 gcloud pubsub subscriptions create subscriber-id \
   --topic=cloud-builds \
   --push-endpoint=service-url \
   --push-auth-service-account=cloud-run-pubsub-invoker@project-id.iam.gserviceaccount.com
```
Onde:
- subscriber-id é o nome que quer atribuir à sua subscrição.
- service-url é o URL gerado pelo Cloud Run para o seu novo serviço.
- project-id é o ID do seu Google Cloud projeto.

As notificações para o seu projeto do Cloud Build estão agora configuradas. Na próxima vez que invocar uma compilação, é criado um problema no repositório do GitHub definido se a compilação corresponder ao filtro que configurou.

Usar o IEC para filtrar eventos de compilação

O Cloud Build usa o CEL com a variável build nos campos indicados no recurso Build para aceder aos campos associados ao seu evento de compilação, como o ID do acionador, a lista de imagens ou os valores de substituição. Pode usar a string filter para filtrar eventos de compilação no ficheiro de configuração de compilação usando qualquer campo listado no recurso Build. Para encontrar a sintaxe exata associada ao seu campo, consulte o ficheiro cloudbuild.proto.

Filtrar por ID do acionador

Para filtrar por ID do acionador, especifique o valor do ID do acionador no campo filter usando build.build_trigger_id, em que trigger-id é o ID do acionador como uma string:

filter: build.build_trigger_id == trigger-id

Filtrar por estado

Para filtrar por estado, especifique o estado de compilação pelo qual quer filtrar no campo filter com build.status.

O exemplo seguinte mostra como filtrar eventos de compilação com um SUCCESS status através do campo filter:

filter: build.status == Build.Status.SUCCESS

Também pode filtrar compilações com vários estados. O exemplo seguinte mostra como filtrar eventos de compilação que têm um estado SUCCESS, FAILURE ou TIMEOUT usando o campo filter:

filter: build.status in [Build.Status.SUCCESS, Build.Status.FAILURE, Build.Status.TIMEOUT]

Para ver os valores de estado adicionais pelos quais pode filtrar, consulte Estado na referência de recursos de criação.

Filtragem por etiqueta

Para filtrar por etiqueta, especifique o valor da etiqueta no campo filter com build.tags, em que tag-name é o nome da etiqueta:

filter: tag-name in build.tags

Pode filtrar com base no número de etiquetas especificadas no evento de compilação usando size. No exemplo seguinte, o campo filter filtra os eventos de compilação que têm exatamente duas etiquetas especificadas, com uma etiqueta especificada como v1:

filter: size(build.tags) == 2 && "v1" in build.tags

Filtrar por imagens

Para filtrar por imagens, especifique o valor da sua imagem no campo filter usando build.images, onde image-name é o nome completo da sua imagem, conforme indicado no Artifact Registry, como us-east1-docker.pkg.dev/my-project/docker-repo/image-one:

filter: image-name in build.images

No exemplo seguinte, os filtros filter são aplicados a eventos de criação 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

Filtrar por hora

Pode filtrar eventos de compilação com base na hora de criação, na hora de início ou na hora de conclusão de uma compilação, especificando uma das seguintes opções no campo filter: build.create_time, build.start_time ou build.finish_time.

No exemplo seguinte, o campo filter usa timestamp para filtrar eventos de compilação com uma hora de pedido para criar a compilação a 20 de julho de 2020 às 06:00:

filter: build.create_time == timestamp("2020-07-20:T06:00:00Z")

Também pode filtrar eventos de criação com base em comparações de tempo. No exemplo seguinte, o campo filter usa timestamp para filtrar eventos de criação com uma hora de início entre 20 de julho de 2020 às 06:00 e 30 de julho de 2020 às 06:00.

filter: timestamp("2020-07-20:T06:00:00Z") >= build.start_time && build.start_time <= timestamp("2020-07-30:T06:00:00Z")

Para saber como os fusos horários são expressos no IEC, consulte a definição de idioma para fusos horários.

Para filtrar por duração de uma compilação, pode usar duration para comparar datas/horas. No exemplo seguinte, o campo filter usa duration para filtrar eventos de compilação com compilações que são executadas durante, pelo menos, cinco minutos:

filter: build.finish_time - build.start_time >= duration("5m")

Filtragem por substituição

Pode filtrar por substituição especificando a variável de substituição no campo filter usando build.substitutions. No exemplo seguinte, o campo filter apresenta as compilaçõ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

Onde:

substitution-variable é o nome da variável de substituição.
substitution-value é o nome do valor de substituição.

Também pode filtrar por valores de variáveis de substituição predefinidos. No exemplo seguinte, o campo filter apresenta compilações com o nome do ramo master e compilações com o nome do repositório github.com/user/my-example-repo. As variáveis de substituição predefinidas 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 quiser filtrar strings através de expressões regulares, pode usar a função matches incorporada. No exemplo abaixo, o campo filter filtra as compilações com o estado FAILURE ou TIMEOUT e que também têm uma variável de substituição de compilação TAG_NAME com um valor que corresponde à 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 dos valores de substituição predefinidos, consulte o artigo Usar substituições predefinidas.

O que se segue?

Saiba mais sobre os notificadores do Cloud Build.
Saiba como subscrever notificações de compilação.
Saiba como escrever um ficheiro de configuração de compilação do Cloud Build.