Cloud Build ti consente di definire trigger webhook, che possono autenticare e accettare gli eventi webhook in entrata. Questi eventi, inviati a un URL personalizzato, ti consentono di connettere direttamente sistemi esterni e sistemi di gestione del codice sorgente esterni, come Bitbucket.com, Bitbucket Server o GitLab, a Cloud Build tramite eventi webhook.
Con i trigger webhook, puoi definire un file di configurazione di compilazione in linea anziché specificare un'origine quando crei il trigger. La configurazione di compilazione in linea ti consente di controllare le operazioni Git e di definire il resto della build.
Questa pagina descrive come creare trigger webhook per automatizzare le build in risposta agli eventi webhook.
Prima di iniziare
Abilita le API Cloud Build e Secret Manager.
Ruoli richiesti per abilitare le API
Per abilitare le API, devi disporre del ruolo IAM Amministratore utilizzo servizi (
roles/serviceusage.serviceUsageAdmin), che contiene l'autorizzazioneserviceusage.services.enable. Scopri come concedere i ruoli.
Per utilizzare i comandi
gcloudin questa pagina, installa Google Cloud CLI.
Creare trigger webhook
Console
Per creare un trigger webhook utilizzando la Google Cloud console:
Apri la pagina Trigger:
Seleziona il progetto nella parte superiore della pagina e fai clic su Apri.
Fai clic su Crea trigger.
Inserisci le seguenti impostazioni del trigger:
- Nome: un nome per il trigger.
Regione: seleziona la regione per il trigger.
Se il file di configurazione della build associato al trigger specifica un pool privato, allora Cloud Build utilizza il pool privato per eseguire la build. In questo caso, la regione specificata nel trigger deve corrispondere alla regione in cui hai creato il pool privato.
Se il file di configurazione della build associato al trigger non specifica un pool privato, Cloud Build utilizza il pool predefinito per eseguire la build nella stessa regione del trigger.
- Descrizione (facoltativo): una descrizione per il trigger.
- Evento: seleziona Evento webhook per configurare il trigger in modo che avvii le build in risposta agli eventi webhook in entrata.
URL webhook: utilizza l'URL webhook per autenticare gli eventi webhook in entrata.
Secret: avrai bisogno di un secret per autenticare gli eventi webhook in entrata. Puoi creare un nuovo secret o utilizzarne uno esistente. Questo secret è separato dal secret associato alla chiave SSH.
Per creare un nuovo secret:
- Seleziona Utilizza un nuovo secret (generato da Cloud Build).
Fai clic su Crea secret.
Viene visualizzata la finestra di dialogo Crea un secret webhook.
Nel campo Nome secret, inserisci un nome per il secret.
Fai clic su Crea secret per salvare il secret, che verrà creato e archiviato automaticamente in Secret Manager.
Per utilizzare un secret esistente:
Seleziona Utilizza un secret esistente o creane uno tuo.
Nel campo Secret, seleziona il nome del secret che vuoi utilizzare dal menu a discesa o segui le istruzioni per aggiungere un secret tramite l'ID risorsa.
Nel campo Versione secret, seleziona la versione del secret dal menu a discesa.
Se utilizzi un secret esistente, potrebbe essere necessario concedere manualmente il ruolo Funzione di accesso di Secret Manager al tuo account di servizio Cloud Build,
service-${PROJECT_NUMBER}@gcp-sa-cloudbuild.iam.gserviceaccount.com. Per saperne di più, consulta Concedere il ruolo Secret Manager al service account.
Dopo aver creato o selezionato il secret, vedrai un'anteprima dell'URL webhook. L'URL conterrà una chiave API generata da Cloud Build e il secret. Se Cloud Build non è in grado di recuperare la chiave API, puoi aggiungerla manualmente alla chiave API all'URL o scoprire come ottenerla se non ne hai ancora una.
Puoi utilizzare l'URL per richiamare un evento webhook effettuando una richiesta HTTP utilizzando il metodo POST.
Utilizza il seguente comando per richiamare un evento webhook:
curl -X POST -H "Content-type: application/json" "https://cloudbuild.googleapis.com/v1/projects/${PROJECT_ID}/locations/${REGION}/triggers/${TRIGGER_NAME}:webhook?key=${API_KEY}&secret=${SECRET_VALUE}&trigger=${TRIGGER_NAME}&projectId=${PROJECT_ID}" -d "{}"Dopo aver completato questi passaggi, il ruolo Funzione di accesso di Secret Manager verrà concesso automaticamente all'agente di servizio Cloud Build,
service-${PROJECT_NUMBER}@gcp-sa-cloudbuild.iam.gserviceaccount.com. Se non vedi questo ruolo aggiunto automaticamente all'agente di servizio, completa i seguenti passaggi descritti in Concedere il ruolo Secret Manager al service account.
Origine (facoltativo): seleziona l'origine da creare quando viene eseguito il trigger webhook. Se stai specificando una configurazione di compilazione in linea, non è necessario specificare l'origine seguente. Puoi specificare 1ª generazione o 2ª generazione come origine. Per saperne di più, consulta Repository Cloud Build.
Repository: dall'elenco dei repository disponibili, seleziona il repository da cui vuoi creare la build.
Ramo o Tag: specifica un'espressione regolare con il valore del ramo o del tag da soddisfare. Per informazioni sulla sintassi accettabile delle espressioni regolari, vedi sintassi RE2.
Controllo commenti: se hai selezionato Richiesta di pull (solo app GitHub) come Evento, scegli una delle seguenti opzioni per controllare se una build verrà eseguita automaticamente dal trigger:
Obbligatorio tranne che per proprietari e collaboratori: quando un proprietario o un collaboratore del repository crea o aggiorna una richiesta di pull, le build vengono eseguite automaticamente dal trigger. Se un contributore esterno avvia l'azione, le build vengono eseguite solo dopo che un proprietario o un collaboratore ha commentato
/gcbrunnella richiesta di pull.Obbligatorio: quando un contributore crea o aggiorna una richiesta di pull, le build vengono eseguite solo dopo che un proprietario o un collaboratore ha commentato
/gcbrunnella richiesta di pull. Le build vengono eseguite ogni volta che viene apportata una modifica a una richiesta di pull.Non obbligatorio: quando un contributore crea o aggiorna una richiesta di pull, le build vengono eseguite automaticamente dai trigger.
Configurazione: seleziona il file di configurazione della build che si trova in 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 origine, 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 della build per la configurazione.
- Dockerfile: utilizza un
Dockerfileper la configurazione. - Buildpacks: utilizza i buildpack per la configurazione.
Posizione: 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
Dockerfileo della directory dei buildpack. Se il tipo di configurazione della build è unDockerfileo un buildpack, dovrai fornire un nome per l'immagine risultante e, facoltativamente, un timeout per la build. Dopo aver fornito il nome dell'immagineDockerfileo buildpack, vedrai un'anteprima del comandodocker buildopackche verrà eseguito dalla build. - Variabili di ambiente buildpack (facoltativo): se hai selezionato
buildpackscome tipo di configurazione, fai clic su Aggiungi variabile di ambiente Pack per specificare le variabili di ambiente e i valori dei buildpack. Per saperne di più sulle variabili di ambiente dei buildpack, consulta Variabili di ambiente. In linea: se hai selezionato File di configurazione di Cloud Build (yaml o json) come opzione di configurazione, puoi specificare la configurazione di compilazione in linea. Fai clic su Apri editor per scrivere il file di configurazione della build nella 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 in linea registra "hello world":
steps: - name: 'ubuntu' args: ['echo', 'hello world']- Repository: se il file di configurazione si trova nel repository remoto, fornisci la posizione del file di configurazione della build, della directory
- Tipo: seleziona il tipo di configurazione da utilizzare per la build.
Sostituzioni (facoltativo): 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 le variabili di sostituzione specifiche del trigger utilizzando questo campo. Puoi anche ottenere i dati utilizzando i binding del payload quando definisci i valori delle variabili di sostituzione.
Filtri (facoltativo): puoi creare una regola all'interno di un trigger che determina se il trigger eseguirà o meno una build in base alle variabili di sostituzione.
- Fai clic su Crea per creare il trigger di build.
gcloud
Per creare un trigger webhook:
gcloud builds triggers create webhook \ --name=TRIGGER_NAME \ --repo=PATH_TO_REPO \ --repo-type=REPO_TYPE \ --secret=PATH_TO_SECRET \ --substitutions=_SUB_ONE='$(body.message.test)',_SUB_TWO='$(body.message.output)' \ --subscription-filter='_SUB_ONE == "prod"' \ --inline-config=PATH_TO_INLINE_BUILD_CONFIG \ --tag=TAG_NAME # --build-config=PATH_TO_BUILD_CONFIG \ # --branch=BRANCH_NAMEDove: +
TRIGGER_NAMEè il nome del trigger. +PATH_TO_REPOè il percorso del repository su cui richiamare una build. Ad esempio,https://www.github.com/owner/repo. +REPO_TYPEè il tipo di repository su cui vuoi richiamare una build.PATH_TO_SECRETè il percorso del secret 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 in linea se utilizzi--inline-config.TAG_NAMEè il nome del tag se vuoi impostare il trigger per la build 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 la build su un ramo.
(Facoltativo) Ottenere una chiave API
Per autenticare l'evento webhook in entrata, è necessaria una chiave API.
Per ottenere una chiave API:
Apri la pagina Credenziali nella Google Cloud console:
Fai clic su Crea credenziali.
Fai clic su Chiave API.
Viene visualizzata una finestra di dialogo con la chiave API creata. Prendi nota della chiave API.
Se vuoi limitare la chiave per le applicazioni dei prodotti, fai clic su Limita chiave per completare i passaggi aggiuntivi per proteggere la chiave. Altrimenti, fai clic su Chiudi.
Per scoprire come limitare la chiave, consulta Applicare le limitazioni delle chiavi API.
(Facoltativo) Concedere il ruolo Secret Manager al account di servizio
Cloud Build concede automaticamente il ruolo Funzione di accesso di Secret Manager ai service account che lo richiedono durante la configurazione del secret. Se non vedi questo ruolo concesso automaticamente al account di servizio necessario, completa i seguenti passaggi per aggiungere manualmente il ruolo in modo che il account di servizio abbia accesso al secret:
Apri la pagina IAM nella console: Google Cloud
(Facoltativo) Per visualizzare gli account forniti da Google, seleziona la casella di controllo Includi concessioni di ruoli fornite da Google.
Prendi nota del account di servizio di build a cui vuoi concedere il ruolo.
Apri la pagina Secret Manager nella Google Cloud console:
Fai clic sul nome del secret.
Viene visualizzata la pagina Dettagli secret.
Fai clic sulla scheda Autorizzazioni.
Fai clic su Concedi l'accesso.
Viene visualizzato il riquadro Concedi l'accesso.
Nella sezione Aggiungi entità, aggiungi l'indirizzo email associato al account di servizio di build.
Nella sezione Assegna i ruoli, seleziona Secret Manager > Funzione di accesso di Secret Manager.
Fai clic su Salva.
Passaggi successivi
- Scopri come creare e gestire i trigger.
- Scopri come creare repository ospitati su Bitbucket Server.
- Scopri come avviare le build manualmente.
- Scopri come visualizzare i risultati della build.
- Scopri come risolvere gli errori di build.
Salvo quando diversamente specificato, i contenuti di questa pagina sono concessi in base alla licenza Creative Commons Attribution 4.0, mentre gli esempi di codice sono concessi in base alla licenza Apache 2.0. Per ulteriori dettagli, consulta le norme del sito di Google Developers. Java è un marchio registrato di Oracle e/o delle sue consociate.
Ultimo aggiornamento 2026-05-16 UTC.