Automatizzare le build in risposta agli eventi webhook

Cloud Build ti consente di definire i trigger di webhook, che possono autenticare e accettare gli eventi webhook in arrivo. Questi eventi, inviati a un URL personalizzato, consentono di connettere direttamente sistemi esterni e sistemi di gestione del codice sorgente esterni, ad esempio Bitbucket.com, Bitbucket Server o GitLab, a Cloud Build mediante eventi webhook.

Con i trigger webhook puoi definire un file di configurazione della compilazione in linea invece di specificare un'origine durante la creazione del trigger. La configurazione di compilazione incorporata consente di avere il controllo sulle operazioni Git e definire il resto della build.

Questa pagina illustra come creare trigger webhook per automatizzare le build in risposta agli eventi webhook.

Prima di iniziare

  • Abilita le API Cloud Build and Secret Manager.

    Abilita le API

  • Per utilizzare i comandi gcloud in questa pagina, installa l'interfaccia a riga di comando di Google Cloud.

Creazione di trigger webhook

console

Per creare un trigger webhook utilizzando Google Cloud Console:

  1. Apri la pagina Trigger:

    Apri la pagina Trigger di build

  2. Seleziona il progetto nella parte superiore della pagina e fai clic su Apri.

  3. Fai clic su Crea trigger.

  4. Inserisci le seguenti impostazioni di attivazione:

    • Nome: un nome per l'attivatore.
    • Area geografica: seleziona l'area geografica per l'attivatore.

      • Se selezioni global come area geografica, Cloud Build utilizza il pool predefinito per eseguire la tua build.
      • Se selezioni un'area geografica non globale e il file di configurazione di compilazione associato al trigger specifica un pool privato, Cloud Build utilizza il pool privato per eseguire la build. In questo caso, l'area geografica specificata nel trigger deve corrispondere a quella in cui hai creato il pool privato.
      • Se selezioni un'area geografica non globale e il file di configurazione di compilazione associato al trigger non specifica un pool privato, Cloud Build utilizza il pool predefinito per eseguire la tua build nella stessa area geografica del trigger.
    • (Facoltativo) Descrizione: una descrizione per l'attivatore.

    • Evento: seleziona Evento webhook per configurare il trigger per avviare le build in risposta agli eventi webhook in arrivo.

    • URL webhook: utilizza l'URL webhook per autenticare gli eventi webhook in entrata.

      • Secret: ti servirà un secret per autenticare gli eventi webhook in entrata. Puoi creare un nuovo secret o utilizzarne uno esistente.

        Per creare un nuovo secret:

        1. Seleziona Crea nuova.
        2. Fai clic su Crea secret.

          Verrà visualizzata la finestra popup Crea un secret webhook.

        3. Nel campo Nome secret, inserisci un nome per il secret.

        4. Fai clic su Crea secret per salvare il secret, che verrà creato e archiviato automaticamente in Secret Manager.

        Per utilizzare un secret esistente:

        1. Seleziona Utilizza esistente.
        2. Nel campo Secret, seleziona il nome del secret che vuoi utilizzare dal menu a discesa o segui le istruzioni per aggiungere un secret in base all'ID risorsa.
        3. Nel campo Versione del secret, seleziona la tua versione del secret dal menu a discesa.

        Se utilizzi un secret esistente, potresti dover concedere manualmente il ruolo Secret Accessor Secret Manager al tuo account di servizio Cloud Build, service-${PROJECT_NUMBER}@gcp-sa-cloudbuild.iam.gserviceaccount.com. Per saperne di più, vedi Concedere il ruolo di Secret Manager al tuo account di servizio.

      Dopo aver creato o selezionato il secret, vedrai un'anteprima dell'URL webhook. L'URL conterrà una chiave API generata da Cloud Build e dal tuo secret. Se Cloud Build non è in grado di recuperare la tua chiave API, puoi aggiungerla manualmente all'URL o scoprire come ottenere una chiave API se non ne hai ancora una.

      Puoi utilizzare l'URL per richiamare un evento webhook effettuando una richiesta HTTP tramite il metodo POST.

       curl -X POST -H "application/json" "https://cloudbuild.googleapis.com/v1/projects/${PROJECT_NAME}/triggers/${TRIGGER_NAME}:webhook?key=${API_KEY}&secret=${SECRET_VALUE}" -d "{}"
      

      Dopo aver completato questi passaggi, il ruolo Secret Manager Secret Accessor verrà concesso automaticamente al tuo account di servizio Cloud Build, service-${PROJECT_NUMBER}@gcp-sa-cloudbuild.iam.gserviceaccount.com. Se non vedi questo ruolo automaticamente aggiunto al tuo account di servizio, completa i passaggi seguenti descritti in Concedere il ruolo di Secret Manager all'account di servizio.

    • (Facoltativo) Origine: seleziona il repository da creare quando viene eseguito il trigger webhook. Se specifichi una configurazione di compilazione in linea, non devi specificare la seguente origine.

    • (Facoltativo) Revisione: seleziona il ramo o il tag da creare quando viene eseguito l'attivatore webhook. Se specifichi una configurazione di compilazione in linea, non devi specificare le seguenti revisioni.

      • Ramo (facoltativo): imposta un trigger per creare su questo ramo. Devi specificare un valore letterale. Le espressioni regolari non sono supportate.
      • (Facoltativo) Tag: imposta un attivatore da creare su questo tag. Devi specificare un valore letterale. Le espressioni regolari non sono supportate.
    • Configurazione: seleziona il file di configurazione della build che si trova nel repository remoto o crea un file di configurazione della build in linea da utilizzare per la build. Se non hai specificato un repository di codice sorgente, devi selezionare un file di configurazione della build in linea come opzione di configurazione.

      • Tipo: seleziona il tipo di configurazione da utilizzare per la build.
        • File di configurazione Cloud Build (yaml o json): Utilizza un file di configurazione di compilazione per la tua configurazione.
        • Dockerfile: utilizza un Dockerfile per la configurazione.
        • Buildpack: utilizza buildpacks per la configurazione.
      • Località: specifica la posizione per la configurazione.

        • Repository: se il file di configurazione si trova nel repository remoto, fornisci la posizione del file di configurazione della build, della directory Dockerfile o della directory buildpacks. Se il tipo di configurazione della build è Dockerfile o buildpack, dovrai fornire un nome per l'immagine risultante e, facoltativamente, un timeout per la build. Dopo aver fornito il nome dell'immagine Dockerfile o buildpack, verrà visualizzata un'anteprima del comando docker build o pack che verrà eseguito dalla build.
        • (Facoltativo) Variabili di ambiente Buildpack: se hai selezionato buildpacks come tipo di configurazione, fai clic su Aggiungi variabile di ambiente Pack per specificare le variabili e i valori dell'ambiente buildpack. Per scoprire di più sulle variabili di ambiente della build, consulta Variabili di ambiente.
        • Inline: se hai selezionato File di configurazione di Cloud Build (yaml o json), puoi specificare la configurazione di compilazione in linea. Fai clic su Apri editor per scrivere il file di configurazione della build in Google Cloud Console utilizzando la sintassi YAML o JSON. Fai clic su Fine per salvare la configurazione della build.

      Nell'esempio seguente, il file di configurazione della compilazione in linea registra echoes "hello world":

       steps:
       - name: 'ubuntu'
         args: ['echo', 'hello world']
      
    • (Facoltativo) Sostituzioni: se hai selezionato il file di configurazione della build come opzione di configurazione della build o hai creato un file di configurazione della build in linea, puoi scegliere di definire variabili di sostituzione specifiche per il trigger utilizzando questo campo. Puoi anche ottenere dati utilizzando le associazioni del carico di lavoro durante la definizione dei valori delle variabili di sostituzione.

    • (Facoltativo) Filtri: puoi creare una regola all'interno di un attivatore che determini se l'attivatore eseguirà o meno una build in base alle variabili di sostituzione.

      Per visualizzare una sintassi di esempio per i filtri che potresti applicare ai tuoi trigger webhook, consulta la sezione Utilizzare la CEL per filtrare gli eventi di build.

  5. Fai clic su Crea per creare il trigger di build.

gcloud

Per creare un trigger webhook:

gcloud alpha builds triggers create webhook \
  --name=TRIGGER_NAME \
  --repo=PATH_TO_REPO \
  --secret=PATH_TO_SECRET \
  --substitutions=_SUB_ONE='$(body.message.test)',_SUB_TWO='$(body.message.output)' \
  --filter='_SUB_ONE == "prod"' \
  --inline-config=PATH_TO_INLINE_BUILD_CONFIG \
  --tag=TAG_NAME
  # --build-config=PATH_TO_BUILD_CONFIG \
  # --branch=BRANCH_NAME

Dove:

  • TRIGGER_NAME è il nome del tuo attivatore.
  • PATH_TO_REPO è il percorso del repository per richiamare una build. Ad esempio, https://www.github.com/owner/repo.
  • PATH_TO_SECRET è il percorso del secret come memorizzato in Secret Manager. Ad esempio, projects/my-project/secrets/my-secret/versions/2.
  • PATH_TO_INLINE_BUILD_CONFIG è il percorso del file di configurazione della build incorporato se utilizzi --inline-config.
  • TAG_NAME è il nome del tag se vuoi impostare l'attivatore per creare su un tag.
  • PATH_TO_BUILD_CONFIG è il percorso del file di configurazione della build se utilizzi --build-config.
  • BRANCH_NAME è il nome del ramo se vuoi impostare il trigger per creare un ramo.

(Facoltativo) Ottenere una chiave API

Per autenticare il tuo evento webhook in arrivo, è necessaria una chiave API.

Per ottenere una chiave API:

  1. Apri la pagina Credenziali in Google Cloud Console:

    Apri la pagina Credenziali

  2. Fai clic su Crea credenziali.

  3. Fai clic su Chiave API.

    Vedrai una finestra di dialogo con la chiave API creata. Prendi nota della tua chiave API.

  4. Se vuoi limitare la tua chiave per le applicazioni del prodotto, fai clic su Limita chiave per completare i passaggi aggiuntivi per proteggere la tua chiave. In caso contrario, fai clic su Chiudi.

    Per scoprire come limitare la tua chiave, consulta l'articolo Applicare limitazioni delle chiavi API.

(Facoltativo) Concessione del ruolo di Secret Manager al tuo account di servizio

Cloud Build concede automaticamente il ruolo Secretor Secret Accessor agli account di servizio che richiedono il ruolo durante la configurazione del secret. Se non vedi che questo ruolo venga concesso automaticamente all'account di servizio necessario, segui questi passaggi per aggiungere manualmente il ruolo in modo che l'account di servizio abbia accesso al secret:

  1. Apri la pagina IAM nella console:

    Apri la pagina IAM

  2. Prendi nota del tuo account di servizio Cloud Build a cui vuoi concedere il ruolo.

  3. Apri la pagina Secret Manager (Console secret) nella console:

    Apri la pagina di Secret Manager

  4. Fai clic sul nome del secret.

    Viene visualizzata la pagina Dettagli secret.

    1. Fai clic sulla scheda Autorizzazioni nel riquadro delle informazioni sul lato destro.

    2. Fai clic su Aggiungi entità.

    3. Nella sezione Nuova entità, aggiungi l'indirizzo email associato al tuo account di servizio Cloud Build.

    4. Nella sezione Seleziona un ruolo, scegli Secret Manager > Secret Manager Secret Accessor.

    5. Fai clic su Aggiungi.

Utilizzo di CEL per filtrare gli eventi di build

Cloud Build utilizza CEL con la variabile build sui campi elencati nella risorsa Build per accedere ai campi associati all'evento di build, come 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 di compilazione utilizzando qualsiasi campo elencato nella risorsa Build. Per trovare la sintassi esatta associata al tuo campo, consulta il file cloudbuild.proto.

Filtrare per ID attivatore

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

filter: build.build_trigger_id == trigger-id

Filtrare per stato

Per filtrare in base allo stato, specifica nel campo filter lo stato della build in base a cui vuoi applicare l'applicazione 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 dello stato in base ai quali puoi applicare il filtro, consulta la sezione Stato sotto il riferimento alla risorsa 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 build utilizzando size. Nell'esempio riportato di seguito, i filtri del campo filter creano eventi con esattamente due tag specificati con un tag specificato come v1:

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

Filtrare tramite immagini

Per filtrare in base alle immagini, specifica il valore dell'immagine nel campo filter utilizzando build.images, dove image-name rappresenta il nome completo dell'immagine, come elencato in Container Registry, come gcr.io/example/image-one:

filter: image-name in build.images

Nell'esempio seguente, il filtro filter mostra gli eventi di build in cui gcr.io/example/image-one o gcr.io/example/image-two sono specificati come nomi di immagini:

filter: "gcr.io/example/image-one" in build.images || "gcr.io/example/image-two" in build.images

Applicazione di filtri in base all'ora

Puoi filtrare gli eventi di build in base a un'ora di creazione, un'ora di inizio o una fine della build specificando una delle seguenti opzioni nel tuo 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'ora della richiesta per creare la build alle 06:00 del 20 luglio 2020:

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

Puoi anche filtrare gli eventi di compilazione in base a confronti in base all'ora. Nell'esempio seguente, il campo filter utilizza timestamp per filtrare gli eventi di build con un'ora di inizio tra le 06:00 del 20 luglio 2020 e delle ore 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 ulteriori informazioni su come i fusi orari vengono espressi in CEL, consulta la definizione della lingua dei 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 una build eseguita per almeno cinque minuti:

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

Filtrare in base alla 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 valore 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 predefiniti. Nel seguente esempio, il campo filter elenca le build con il nome della filiale master e quelle che hanno 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 espressioni regolari, puoi utilizzare la funzione matches integrata. Nell'esempio riportato di seguito, il campo filter filtra in base alle build con uno stato FAILURE o TIMEOUT, che hanno anche una variabile di sostituzione 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 Utilizzo di sostituzioni predefinite.

Passaggi successivi