Google utilizza la tecnologia AI per tradurre i contenuti nella tua lingua preferita. Le traduzioni generate dall'AI potrebbero contenere errori.

Configura le notifiche dei problemi di GitHub

Cloud Build può inviarti notifiche sugli aggiornamenti delle build inviandoti notifiche ai canali selezionati. Questa pagina spiega come configurare le notifiche utilizzando GitHub Issues notifier.

Prima di iniziare

Abilita le API Cloud Build, Compute Engine, Cloud Run, Pub/Sub e Secret Manager.
Ruoli richiesti per abilitare le API
Per abilitare le API, devi disporre dell'autorizzazione serviceusage.services.enable. Se hai creato il progetto, probabilmente disponi già di questa autorizzazione tramite il ruolo Proprietario (roles/owner). In caso contrario, puoi ottenere questa autorizzazione tramite il ruolo Amministratore utilizzo dei servizi (roles/serviceusage.serviceUsageAdmin). Scopri come concedere i ruoli.
Abilita le API

Installa Google Cloud CLI.

Configurazione delle notifiche dei problemi di GitHub

La sezione seguente spiega come configurare manualmente le notifiche dei problemi di GitHub utilizzando lo strumento di notifica dei problemi di GitHub. Se invece vuoi automatizzare la configurazione, consulta Automatizzazione della configurazione per le notifiche.

Per configurare GitHub Issues:

Crea un token di accesso personale GitHub:
1. Vai alle impostazioni di GitHub per creare un nuovo token.
2. Seleziona l'ambito repo.
  
  Nota: questo concede l'accesso completo ai repository, inclusi quelli privati.
3. Fai clic su Genera token.
Archivia il token GitHub in Secret Manager:
1. Apri la pagina Secret Manager nella console Google Cloud :
  
  Apri la pagina Secret Manager
2. Fai clic su Crea secret.
3. Inserisci un nome per il secret.
4. In Valore segreto, aggiungi il tuo token GitHub.
5. Per salvare il secret, fai clic su Crea secret.
Anche se il account di servizio Cloud Run potrebbe avere il ruolo Editor per il tuo progetto, questo ruolo non è sufficiente per accedere al tuo secret in Secret Manager. Per concedere al account di servizio Cloud Run l'accesso al tuo secret:
1. Vai alla pagina IAM nella console Google Cloud :
  
  Apri la pagina IAM
2. Individua l'account di servizio Compute Engine predefinito associato al tuo progetto:
  
  Il tuo service account predefinito di Compute Engine sarà simile al seguente:
```
project-number-compute@
```
  Prendi nota del tuo service account Compute Engine predefinito.
  
  Nota: per impostazione predefinita, Cloud Run esegue le immagini del notificatore con l'account di servizio predefinito di Compute Engine e lo utilizza per recuperare il secret. Per saperne di più sui service account di runtime, consulta Service account di runtime.
3. Apri la pagina Secret Manager nella console Google Cloud :
  
  Apri la pagina Secret Manager
4. Fai clic sul nome del secret che contiene il secret per il token GitHub.
5. Nella scheda Autorizzazioni, fai clic su Aggiungi membro.
6. Aggiungi l'account di servizio predefinito di Compute Engine associato al tuo progetto come membro.
7. Seleziona l'autorizzazione Secret Manager Secret Accessor come ruolo.
8. Fai clic su Salva.
Concedi al tuo account di servizio Cloud Run l'autorizzazione a leggere dai bucket Cloud Storage:
1. Vai alla pagina IAM nella console Google Cloud :
  
  Apri la pagina IAM
2. Individua l'account di servizio Compute Engine predefinito associato al tuo progetto:
  
  Il tuo service account predefinito di Compute Engine sarà simile al seguente:
```
project-number-compute@
```
3. Fai clic sull'icona a forma di matita nella riga contenente il service account predefinito di Compute Engine. Viene visualizzata la scheda accesso in modifica.
4. Fai clic su Aggiungi un altro ruolo.
5. Aggiungi il seguente ruolo:
  - Storage Object Viewer
  Nota: se vuoi concedere le autorizzazioni a livello di bucket anziché a livello di progetto, aggiungi il ruolo Proprietario oggetti legacy Storage al bucket quando ne crei uno. Per saperne di più, consulta Concedere ruoli a livello di progetto, di bucket o di cartella gestita.
6. Fai clic su Salva.
Scrivi un file di configurazione del modello per descrivere il formato che devono assumere i problemi GitHub creati:

Nel seguente file di configurazione del modello di esempio, i campi title e body utilizzano variabili di sostituzione della build:
```
{
    "title": "Build {{.Build.BuildTriggerId}}: {{.Build.Status}}",
    "body": "[{{.Build.ProjectId}}] {{.Build.BuildTriggerId}} status: **{{.Build.Status}}**\n\n[View Logs]({{.Build.LogUrl}})"
}
```
Per visualizzare l'esempio, consulta il file di configurazione del modello per la notifica dei problemi di GitHub.

È possibile impostare campi aggiuntivi dai parametri del corpo disponibili dall'endpoint API GitHub per la creazione di un problema.
Scrivi un file di configurazione del sistema di notifica per configurare il sistema di notifica dei problemi di GitHub e filtrare gli eventi di build:

Nel seguente file di configurazione del notificatore, il campo filter utilizza il Common Expression Language con la variabile disponibile build per filtrare gli eventi di build con lo stato 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: MY_USER/MY_REPO
  secrets:
  - name: github-token
    value: projects/PROJECT_ID/secrets/SECRET_NAME/versions/latest
```
Dove:
- githubToken è la variabile di configurazione utilizzata in questo esempio per fare riferimento al token GitHub archiviato in Secret Manager. Il nome della variabile specificato qui deve corrispondere al campo name in secrets.
- BUCKET_NAME è il nome del tuo bucket.
- TEMPLATE_FILE_NAME è il nome del file modello.
- MY_USER/MY_REPO è il nome del repository in cui verranno creati i problemi.
- PROJECT_ID è l'ID del tuo progetto Google Cloud .
- SECRET_NAME è il nome del tuo secret che contiene il token GitHub.
Per visualizzare l'esempio, consulta il file di configurazione del sistema di notifica per il sistema di notifica dei problemi di GitHub.

Per altri campi in base ai quali puoi filtrare, consulta la risorsa Build. Per altri esempi di filtri, vedi Utilizzo di CEL per filtrare gli eventi di build.
Carica il file di configurazione del sistema di notifica e il file del modello in un bucket Cloud Storage:
1. Se non hai un bucket Cloud Storage, esegui il comando seguente per creare un bucket, dove BUCKET_NAME è il nome che vuoi assegnare al bucket, soggetto ai requisiti di denominazione.
```
gcloud storage buckets create gs://BUCKET_NAME/
```
2. Carica il file di configurazione del sistema di notifica e il file modello nel bucket:
```
gcloud storage cp CONFIG_FILE_NAME gs://BUCKET_NAME/CONFIG_FILE_NAME

gcloud storage cp TEMPLATE_FILE_NAME gs://BUCKET_NAME/TEMPLATE_FILE_NAME
```
  Dove:
  - BUCKET_NAME è il nome del tuo bucket.
  - CONFIG_FILE_NAME è il nome del file di configurazione.
  - TEMPLATE_FILE_NAME è il nome del file modello.
Esegui il deployment del notifier in 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
```
Dove:
- SERVICE_NAME è il nome del servizio Cloud Run in cui esegui il deployment dell'immagine.
- CONFIG_PATH è il percorso del file di configurazione del sistema di notifica per il sistema di notifica dei problemi di GitHub, gs://BUCKET_NAME/CONFIG_FILE_NAME.
- PROJECT_ID è l'ID del tuo progetto Google Cloud .
Il comando gcloud run deploy recupera l'ultima versione dell'immagine ospitata da Artifact Registry di proprietà di Cloud Build. Cloud Build supporta le immagini di notifica per nove mesi. Dopo nove mesi, Cloud Build elimina la versione dell'immagine. Se vuoi utilizzare una versione precedente dell'immagine, devi specificare la versione semantica completa del tag immagine nell'attributo image del comando gcloud run deploy. Le versioni e i tag delle immagini precedenti sono disponibili in Artifact Registry.

Nota: durante l'esecuzione di questo comando, potrebbe esserti chiesto di specificare argomenti aggiuntivi come --region o --platform. Per scoprire di più sui parametri che puoi passare al comando gcloud run deploy, consulta Deployment in Cloud Run. Se non riesci a eseguire il deployment del notifier utilizzando questo comando, consulta la guida alla risoluzione dei problemi di Cloud Run per trovare soluzioni su come risolvere gli errori di deployment.
Crea un account di servizio per rappresentare l'identità della sottoscrizione Pub/Sub:
```
gcloud iam service-accounts create SUB_IDENTITY_SERVICE_ACCOUNT \
  --display-name "SUB_IDENTITY_SERVICE_ACCOUNT_DISPLAY_NAME"
```
Dove:
- SUB_IDENTITY_SERVICE_ACCOUNT è un nome per il account di servizio.
- SUB_IDENTITY_SERVICE_ACCOUNT_DISPLAY_NAME è un nome visualizzato per il account di servizio.
Nota: questo account di servizio è diverso dal account di servizio Pub/Sub, che Google Cloud viene creato quando crei una sottoscrizione Pub/Sub. Il account di servizio Pub/Sub ha l'indirizzo service-PROJECT_NUMBER@gcp-sa-pubsub..
Concedi al account di servizio di identità della sottoscrizione Pub/Sub le autorizzazioni necessarie per creare token di autenticazione nel tuo progettoGoogle Cloud .
```
gcloud iam service-accounts add-iam-policy-binding \
    SUB_IDENTITY_SERVICE_ACCOUNT@PROJECT_ID.i \
    --member=serviceAccount:service-PROJECT_NUMBER@gcp-sa-pubsub. \
    --role=roles/iam.serviceAccountTokenCreator
```
Dove:
- PROJECT_ID è l'ID del tuo progetto Google Cloud .
- PROJECT_NUMBER è il numero del tuo progetto Google Cloud .
Concedi all'account di servizio SUB_IDENTITY_SERVICE_ACCOUNT il ruolo Invoker Cloud Run:
```
gcloud run services add-iam-policy-binding SERVICE_NAME \
   --member=serviceAccount:SUB_IDENTITY_SERVICE_ACCOUNT@PROJECT_ID. \
   --role=roles/run.invoker
```
Dove:
- SERVICE_NAME è il nome del servizio Cloud Run in cui esegui il deployment dell'immagine.
- PROJECT_ID è l'ID del tuo progetto Google Cloud .
Crea l'argomento cloud-builds per ricevere messaggi di aggiornamento della build per il tuo notifier:
```
gcloud pubsub topics create cloud-builds
```
Puoi anche definire un nome dell'argomento personalizzato nel file di configurazione della build in modo che i messaggi vengano inviati all'argomento personalizzato. In questo caso, devi creare un argomento con lo stesso nome dell'argomento personalizzato:
```
gcloud pubsub topics create topic-name
```
Per ulteriori informazioni, consulta la sezione Argomenti Pub/Sub per le notifiche di build.
Crea un abbonato push Pub/Sub per il tuo sistema di notifica:

     gcloud pubsub subscriptions create subscriber-id \
       --topic=cloud-builds \
       --push-endpoint=SERVICE_URL \
       --push-auth-service-account=SUB_IDENTITY_SERVICE_ACCOUNT@PROJECT_ID.

Dove: + SUBSCRIBER_ID è il nome che vuoi dare al tuo abbonamento. + SERVICE_URL è l'URL generato da Cloud Run per il nuovo servizio. + PROJECT_ID è l'ID del tuo progetto 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.

Le notifiche per il tuo progetto Cloud Build sono ora configurate. La prossima volta che richiami una build, verrà creato un problema nel repository GitHub definito se la build corrisponde al filtro che hai configurato.

Utilizzo di CEL per filtrare gli eventi di build

Cloud Build utilizza CEL con la variabile build nei campi elencati nella risorsa Build per accedere ai campi associati all'evento di build, ad esempio l'ID trigger, l'elenco delle immagini o i valori di sostituzione. Puoi utilizzare la stringa filter per filtrare gli eventi di build nel file di configurazione della build utilizzando qualsiasi campo elencato nella risorsa Build. Per trovare la sintassi esatta associata al campo, consulta il file cloudbuild.proto.

Filtro per ID trigger

Per filtrare in base all'ID trigger, specifica il valore dell'ID trigger nel campo filter utilizzando build.build_trigger_id, dove trigger-id è l'ID trigger come stringa:

filter: build.build_trigger_id == trigger-id

Filtrare per stato

Per filtrare in base allo stato, specifica lo stato della build in base al quale vuoi filtrare nel campo filter utilizzando build.status.

L'esempio seguente mostra come filtrare gli eventi di build con uno stato SUCCESS utilizzando il campo filter:

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

Puoi anche filtrare le build con stati diversi. L'esempio seguente mostra come filtrare gli eventi di build con stato SUCCESS, FAILURE o TIMEOUT utilizzando il campo filter:

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

Per visualizzare altri valori di stato in base ai quali puoi filtrare, consulta Stato nella sezione Riferimento alle risorse di build.

Filtro per tag

Per filtrare in base al tag, specifica il valore del tag nel campo filter utilizzando build.tags, dove tag-name è il nome del tag:

filter: tag-name in build.tags

Puoi filtrare in base al numero di tag specificati nell'evento di build utilizzando size. Nell'esempio seguente, il campo filter filtra gli eventi di build che hanno esattamente due tag specificati, uno dei quali è v1:

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

Filtrare per immagini

Per filtrare in base alle immagini, specifica il valore dell'immagine nel campo filter utilizzando build.images, dove image-name è il nome completo dell'immagine elencata in Artifact Registry, ad esempio us-east1-docker.pkg.dev/my-project/docker-repo/image-one:

filter: image-name in build.images

Nell'esempio seguente, filter filtra gli eventi di build che hanno us-east1-docker.pkg.dev/my-project/docker-repo/image-one o us-east1-docker.pkg.dev/my-project/docker-repo/image-two specificato come nomi delle immagini:

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

Filtro per ora

Puoi filtrare gli eventi di build in base all'ora di creazione, all'ora di inizio o all'ora di fine di una build specificando una delle seguenti opzioni nel campo filter: build.create_time, build.start_time o build.finish_time.

Nell'esempio seguente, il campo filter utilizza timestamp per filtrare gli eventi di build con un orario di richiesta per creare la build il 20 luglio 2020 alle 06:00:

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

Puoi anche filtrare gli eventi di build in base ai confronti temporali. Nell'esempio seguente, il campo filter utilizza timestamp per filtrare gli eventi di build con un orario di inizio compreso tra le 06:00 del 20 luglio 2020 e le 06:00 del 30 luglio 2020.

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

Per scoprire di più su come vengono espressi i fusi orari in CEL, consulta la definizione del linguaggio per i fusi orari.

Per filtrare in base alla durata di una build, puoi utilizzare duration per confrontare i timestamp. Nell'esempio seguente, il campo filter utilizza duration per filtrare gli eventi di build con build eseguite per almeno cinque minuti:

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

Filtro per sostituzione

Puoi filtrare per sostituzione specificando la variabile di sostituzione nel campo filter utilizzando build.substitutions. Nell'esempio seguente, il campo filter elenca le build che contengono la variabile di sostituzione substitution-variable e controlla se substitution-variable corrisponde al substitution-value specificato:

filter: build.substitutions[substitution-variable] == substitution-value

Dove:

substitution-variable è il nome della variabile di sostituzione.
substitution-value è il nome del valore di sostituzione.

Puoi anche filtrare in base ai valori delle variabili di sostituzione predefinite. Nell'esempio seguente, il campo filter elenca le build con il nome del ramo master e le build con il nome del repository github.com/user/my-example-repo. Le variabili di sostituzione predefinite BRANCH_NAME e REPO_NAME vengono trasmesse come chiavi a build.substitutions:

filter: build.substitutions["BRANCH_NAME"] == "master" && build.substitutions["REPO_NAME"] == "github.com/user/my-example-repo"

Se vuoi filtrare le stringhe utilizzando le espressioni regolari, puoi utilizzare la funzione integrata matches. Nell'esempio riportato di seguito, il campo filter filtra le build con stato FAILURE o TIMEOUT e che hanno anche una variabile di sostituzione della build TAG_NAME con un valore che corrisponde all'espressione regolare 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}$")

Per visualizzare un elenco dei valori di sostituzione predefiniti, consulta la sezione Utilizzare le sostituzioni predefinite.

Passaggi successivi

Scopri di più sui notifier di Cloud Build.
Scopri come iscriverti alle notifiche di build.
Scopri come scrivere un file di configurazione di compilazione di Cloud Build.