Automatizzare le build in risposta agli eventi webhook

Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

Cloud Build ti consente di definire i trigger 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 esterno, come Bitbucket.com, Bitbucket Server o GLab, a Cloud Build tramite eventi webhook.

Con i trigger webhook, puoi definire un file di configurazione di compilazione in linea anziché specificare un'origine durante la creazione del trigger. La configurazione in linea ti 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 Google Cloud CLI.

Creazione di trigger webhook

Console

Per creare un trigger webhook utilizzando la console Google Cloud:

  1. Apri la pagina Attivatori:

    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 globale come area geografica, Cloud Build utilizza il pool predefinito per eseguire la 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, la regione 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 build nella stessa regione del trigger.
    • (Facoltativo) Descrizione: una descrizione dell'attivatore.

    • Evento: seleziona Evento webhook per configurare il trigger in modo da 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 arrivo. Puoi creare un nuovo secret o utilizzarne uno esistente. Il secret è separato dal secret associato alla chiave SSH.

        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 versione del tuo 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 scoprire di più, consulta Concedere il ruolo Secret Manager all'account di servizio.

      Dopo aver creato o selezionato il secret, vedrai un'anteprima dell'URL webhook. L'URL contiene una chiave API generata da Cloud Build e dal secret. Se Cloud Build non è in grado di recuperare la 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 con 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 Funzione di accesso secret di Secret Manager verrà concesso automaticamente al tuo account di servizio Cloud Build, service-${PROJECT_NUMBER}@gcp-sa-cloudbuild.iam.gserviceaccount.com. Se non vedi che questo ruolo viene aggiunto automaticamente al tuo account di servizio, completa i passaggi seguenti descritti in Concessione del ruolo Secret Manager all'account di servizio.

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

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

      • (Facoltativo) Ramo: imposta un trigger per creare un ramo. Devi specificare un valore letterale. Le espressioni regolari non sono supportate.
      • (Facoltativo) Tag: imposta un attivatore da basare su questo tag. Devi specificare un valore letterale. Le espressioni regolari non sono supportate.
    • Configurazione: seleziona il file di configurazione della build situato nel repository remoto o crea un file di configurazione della build incorporato da utilizzare per la tua 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 di Cloud Build (yaml o json): utilizza un file di configurazione di compilazione per la configurazione.
        • Dockerfile: utilizza un Dockerfile per la configurazione.
        • Buildpack: utilizza i buildpack per la configurazione.
      • Località: specifica la posizione della configurazione.

        • Repository: se il file di configurazione si trova nel tuo 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 un 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, vedrai un'anteprima del comando docker build o pack che verrà eseguito.
        • (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 di ambiente buildpack. Per ulteriori informazioni sulle variabili di ambiente buildpack, consulta Variabili di ambiente.
        • In linea: se hai selezionato File di configurazione Cloud Build (yaml o json) come opzione di configurazione, puoi specificare la configurazione di build 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 build incorporato 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 del trigger utilizzando questo campo. Puoi ottenere i dati anche utilizzando le associazioni di payload durante la definizione dei valori delle variabili di sostituzione.

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

      Per visualizzare una sintassi di esempio per l'applicazione di filtri ai trigger webhook, consulta Utilizzo di CEL per filtrare gli eventi di build.

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

gcloud

Per creare un trigger di 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 su. Ad esempio, https://www.github.com/owner/repo.
  • PATH_TO_SECRET è il percorso del secret come archiviato 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 in modo che utilizzi i 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 l'evento webhook in arrivo, è necessaria una chiave API.

Per ottenere una chiave API:

  1. Apri la pagina Credentials nella console Google Cloud:

    Apri la pagina Credenziali

  2. Fai clic su Crea credenziali.

  3. Fai clic su Chiave API.

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

  4. Se vuoi limitare la chiave per le applicazioni di prodotto, fai clic su Limita chiave per completare ulteriori passaggi per proteggere la chiave. In caso contrario, fai clic su Chiudi.

    Per scoprire come limitare la chiave, consulta la sezione Applicare restrizioni alle chiavi API.

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

Cloud Build concede automaticamente il ruolo Funzione di accesso secret di Secret Manager agli account di servizio che richiedono il ruolo durante la configurazione del secret. Se non vedi che questo ruolo viene concesso automaticamente all'account di servizio necessario, completa i passaggi seguenti per aggiungere manualmente il ruolo in modo che l'account di servizio abbia accesso al tuo secret:

  1. Apri la pagina IAM in Google Cloud 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 in Google Cloud 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 a destra.

    2. Fai clic su Aggiungi entità.

    3. Nella sezione New Principal (Nuova entità), aggiungi l'email associata al tuo account di servizio Cloud Build.

    4. Nella sezione Seleziona un ruolo, seleziona 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 al tuo evento di build, come il tuo 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 l'esatta sintassi associata al tuo campo, consulta il file cloudbuild.proto.

Filtrare per ID trigger

Per filtrare in base all'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

Applicazione dei filtri 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 uno stato SUCCESS, FAILURE o TIMEOUT utilizzando il campo filter:

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

Per visualizzare i valori aggiuntivi di stato in base ai quali puoi applicare un filtro, consulta la sezione Stato sotto il riferimento alle risorse Build.

Applicazione di filtri in base al tag

Per filtrare in base al tag, specifica il valore del tag nel campo filter utilizzando build.tags, dove tag-name corrisponde al 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, il campo filter filtra i filtri per creare gli eventi con esattamente due tag specificati con un tag specificato come v1:

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

Filtrare in base alle 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, come elencato in Container Registry, ad esempio gcr.io/example/image-one:

filter: image-name in build.images

Nel seguente esempio, filter filtra gli eventi di build con gcr.io/example/image-one o gcr.io/example/image-two specificati come nomi di immagini:

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

Filtrare in base all'ora

Puoi filtrare gli eventi di build in base a una data di creazione, un'ora di inizio o di fine di una 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 di creazione della build al 20 luglio 2020 alle 6:00:

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

Puoi anche filtrare gli eventi di build 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 il 20 e le 6:00 del 20 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 sono espressi nel CEL, consulta la definizione della lingua 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 una build eseguita per almeno cinque minuti:

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

Filtrare per sostituzione

Puoi filtrare in base alla 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. Nell'esempio seguente, il campo filter elenca le build che hanno il nome del ramo 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 passate come chiavi in 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 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 di sostituzioni predefinite, vedi Utilizzare le sostituzioni predefinite.

Passaggi successivi