Configurare le notifiche relative ai problemi di GitHub

Cloud Build può inviarti notifiche relative agli aggiornamenti delle build inviandoti notifiche ai canali che preferisci. Questa pagina spiega come configurare le notifiche utilizzando il notificatore dei problemi di GitHub.

Prima di iniziare

  • Enable the Cloud Build, Compute Engine, Cloud Run, Pub/Sub, and Secret Manager APIs.

    Enable the APIs

Configurare le notifiche relative ai problemi di GitHub

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

Per configurare i problemi di GitHub:

  1. Crea un token di accesso personale GitHub:

    1. Vai alle impostazioni di GitHub per creare un nuovo token.

    2. Seleziona l'ambito repo.

    3. Fai clic su Genera token.

  2. Memorizza 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 secret, aggiungi il token GitHub.

    5. Per salvare il secret, fai clic su Crea secret.

  3. Sebbene il tuo account di servizio Cloud Run possa avere il ruolo Editor per il tuo progetto, il ruolo Editor non è sufficiente per accedere al tuo secret in Secret Manager. Dovrai concedere all'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 predefinito di Compute Engine associato al tuo progetto:

      Il tuo account di servizio predefinito Compute Engine sarà simile al seguente:

      project-number-compute@developer.gserviceaccount.com

      Prendi nota del tuo account di servizio predefinito di Compute Engine.

    3. Apri la pagina Secret Manager nella console Google Cloud :

      Apri la pagina Secret Manager

    4. Fai clic sul nome dello secret che contiene il token GitHub.

    5. Nella scheda Autorizzazioni, fai clic su Aggiungi membro.

    6. Aggiungi l'account di servizio predefinito di Compute Engine associato al progetto come membro.

    7. Seleziona l'autorizzazione Secret Manager Secret Accessor come ruolo.

    8. Fai clic su Salva.

  4. Concedi all'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 predefinito di Compute Engine associato al tuo progetto:

      Il tuo account di servizio predefinito Compute Engine sarà simile al seguente:

      project-number-compute@developer.gserviceaccount.com

    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:

      • Visualizzatore oggetti Storage

    6. Fai clic su Salva.

  5. Scrivi un file di configurazione del modello per descrivere il formato che devono avere i problemi GitHub creati:

    Nel seguente esempio di file di configurazione del modello, i campi title e body utilizzano le variabili di sostituzione della compilazione: 

    {
    "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 il notifier dei problemi di GitHub.

    È possibile impostare campi aggiuntivi dai parametri del corpo disponibili nell'endpoint dellendpoint API per la creazione di un problema.

  6. Scrivi un file di configurazione del notificatore per configurare il notificatore dei problemi di GitHub e filtrare in base agli eventi di compilazione:

    Nel seguente esempio di file di configurazione del notifier, il campo filter utilizza il Common Expression Language con la variabile disponibile build per filtrare gli eventi di compilazione con uno 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: myuser/myrepo
  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 bucket.
    • template-file-name è il nome del file del modello.
    • myuser/myrepo è il nome del repository in base al quale verranno creati i problemi.
    • project-id è l'ID del tuo progetto Google Cloud .
    • secret-name è il nome dello secret che contiene il token GitHub.

    Per visualizzare l'esempio, consulta il file di configurazione del notifier per il notifier dei problemi GitHub.

    Per altri campi in base ai quali puoi filtrare, consulta la risorsa Build. Per altri esempi di filtri, consulta Utilizzo di CEL per filtrare gli eventi di build.

  7. Carica il file di configurazione e il file del modello del notifier in un bucket Cloud Storage:

    1. Se non hai un bucket Cloud Storage, esegui il seguente comando per crearne uno, dove bucket-name è il nome che vuoi assegnare al bucket, rispettando i requisiti di denominazione.

      gcloud storage buckets create gs://bucket-name/

    2. Carica il file di configurazione e il file modello del notifier nel 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

      Dove:

      • bucket-name è il nome del bucket.
      • config-file-name è il nome del file di configurazione.
      • template-file-name è il nome del file del modello.

  8. 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 stai eseguendo il deployment dell'immagine.

    • config-path è il percorso del file di configurazione del notifier per il notifier dei problemi GitHub, gs://bucket-name/config-file-name.

    • project-id è l'ID del tuo progetto Google Cloud .

    Il comando gcloud run deploy estrae la versione più recente dell'immagine ospitata dall'Artifact Registry di proprietà di Cloud Build. Cloud Build supporta le immagini di avviso per nove mesi. Dopo nove mesi, Cloud Build elimina la versione dell'immagine. Se vuoi utilizzare una versione dell'immagine precedente, 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.

  9. Concedi le autorizzazioni Pub/Sub per creare token di autenticazione nel tuo progetto:

     gcloud projects add-iam-policy-binding project-id \
   --member=serviceAccount:service-project-number@gcp-sa-pubsub.iam.gserviceaccount.com \
   --role=roles/iam.serviceAccountTokenCreator

    Dove:

    • project-id è l'ID del tuo progetto Google Cloud .
    • project-number è il numero del tuo progetto Google Cloud .

  10. Crea un account di servizio per rappresentare l'identità della tua sottoscrizione Pub/Sub:

    gcloud iam service-accounts create cloud-run-pubsub-invoker \
  --display-name "Cloud Run Pub/Sub Invoker"

    Puoi utilizzare cloud-run-pubsub-invoker o un nome univoco all'interno del tuo progetto Google Cloud.

  11. Concedi all'account di servizio cloud-run-pubsub-invoker l'autorizzazione Invoker di 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

    Dove:

    • service-name è il nome del servizio Cloud Run in cui stai eseguendo il deployment dell'immagine.
    • project-id è l'ID del tuo progetto Google Cloud .

  12. Crea l'argomento cloud-builds per ricevere i messaggi di aggiornamento della compilazione per il tuo notifier:

    gcloud pubsub topics create cloud-builds

  13. Crea un abbonato push Pub/Sub per il tuo notifier:

     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

    Dove:

    • subscriber-id è il nome che vuoi assegnare all'abbonamento.
    • service-url è l'URL generato da Cloud Run per il nuovo servizio.
    • project-id è l'ID del tuo progetto Google Cloud .

Le notifiche per il tuo progetto Cloud Build sono state 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 compilazione, ad esempio l'ID trigger, l'elenco di immagini o i valori di sostituzione. Puoi utilizzare la stringa filter per filtrare gli eventi di compilazione 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.

Filtrare per ID attivatore

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

filter: build.build_trigger_id == trigger-id

Filtrare per stato

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

L'esempio seguente mostra come filtrare gli eventi di compilazione 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 compilazione 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 per i quali puoi filtrare, consulta Stato nella sezione Riferimento alle risorse di Build.

Filtrare 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 compilazione utilizzando size. Nell'esempio seguente, il campo filter filtra gli eventi di compilazione che hanno esattamente due tag specificati, con un tag specificato come v1:

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

Filtrare per immagini

Per filtrare per immagini, specifica il valore dell'immagine nel campo filter utilizzando build.images, dove image-name è il nome completo dell'immagine come elencato 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 compilazione 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

Filtrare per ora

Puoi filtrare gli eventi di compilazione in base all'ora di creazione, all'ora di inizio o all'ora di fine di una compilazione 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 compilazione con un orario della richiesta per creare la compilazione il 20 luglio 2020 alle 06:00:

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

Puoi anche filtrare gli eventi di compilazione in base ai confronti di tempo. Nell'esempio seguente, il campo filter utilizza timestamp per filtrare gli eventi di compilazione con un'ora di inizio compresa 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 i fusi orari vengono espressi in CEL, consulta la definizione di linguaggio per i fusi orari.

Per filtrare in base alla durata di una compilazione, puoi utilizzare duration per confrontare i timestamp. Nell'esempio seguente, il campo filter utilizza duration per filtrare gli eventi di build con build in esecuzione 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. Nel seguente esempio, il campo filter elenca le build che contengono la variabile di sostituzione substitution-variable e controlla se substitution-variable corrisponde a 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 sostitutivo.

Puoi anche filtrare in base ai valori predefiniti delle variabili di sostituzione. 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 passate 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 espressioni regolari, puoi utilizzare la funzione matches integrata. Nell'esempio seguente, il campo filter filtra per le build con stato FAILURE o TIMEOUT e che hanno anche una variabile di sostituzione della build TAG_NAME con un valore corrispondente 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 Utilizzare le sostituzioni predefinite.

Passaggi successivi