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

Automatizzare le build in risposta agli eventi webhook

Cloud Build ti consente di definire trigger di webhook per autenticare e accettare eventi webhook in entrata. Questi eventi, inviati a un URL personalizzato, ti consentono di connettere sistemi esterni e piattaforme di gestione del codice sorgente, come Bitbucket.com, Bitbucket Server o GitLab, direttamente a Cloud Build.

Con i trigger di webhook, puoi specificare una configurazione di compilazione in linea anziché un repository di origine. Questa configurazione in linea ti offre il controllo sulle operazioni Git e sul workflow di build. Per automatizzare le build sugli eventi del repository, puoi utilizzare i trigger del repository Cloud Build, che si integrano direttamente con provider come GitHub e GitLab.

Con i trigger del webhook, puoi definire un file di configurazione di compilazione in linea anziché specificare un'origine durante la creazione del trigger. La configurazione di compilazione in linea ti consente di controllare le operazioni Git e di definire il resto della compilazione.

In questa pagina viene descritto come creare trigger di webhook per automatizzare le build in risposta agli eventi di webhook.

Prima di iniziare

Abilita le API Cloud Build e Secret Manager, se non sono già abilitate.
Ruoli richiesti per abilitare le API
Per abilitare le API, devi disporre dell'autorizzazione serviceusage.services.enable. Se hai creato il progetto, probabilmente hai già questa autorizzazione tramite il ruolo Proprietario (roles/owner). In caso contrario, puoi ottenere questa autorizzazione tramite il ruolo Amministratore Service Usage (roles/serviceusage.serviceUsageAdmin). Scopri come concedere i ruoli.
Abilita le API

Per utilizzare i comandi gcloud in questa pagina, installa Google Cloud CLI.

Nota: se hai già installato gcloud CLI, assicurati di avere l'ultima versione disponibile eseguendo gcloud components update.
Se il trigger del webhook utilizza un repository Cloud Build come origine, assicurati di avere familiarità con i repository Cloud Build.

Crea trigger webhook

Console

Per creare un trigger del webhook utilizzando la console Google Cloud :

Apri la pagina Trigger:

Apri la pagina Trigger di build
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 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 alla regione in cui hai creato il pool privato.
  - Se 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 del 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. Per autenticare gli eventi webhook in entrata, devi utilizzare un secret. Puoi creare un nuovo secret o utilizzarne uno esistente. Questo secret è separato da quello associato alla tua chiave SSH.
  
  Per creare un secret:
  1. Seleziona Utilizza un nuovo secret (generato da Cloud Build).
  2. Fai clic su Crea secret.
    
    Verrà visualizzata la finestra di dialogo 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 un secret esistente o creane uno tuo.
  2. Nel campo Secret, seleziona il nome del secret che vuoi utilizzare dal menu a discesa o segui le istruzioni per aggiungere un secret tramite ID risorsa.
  3. Nel campo Versione secret, seleziona la versione del secret dal menu a discesa.
    
    Se utilizzi un secret esistente, potresti dover concedere manualmente il ruolo Secret Manager Secret Accessor al tuo account di servizio Cloud Build, service-${PROJECT_NUMBER}@gcp-sa-cloudbuild.iam.gserviceaccount.com. Per saperne di più, consulta Concedi 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 tuo secret. Se Cloud Build non riesce a 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.
    
    Dopo aver completato questi passaggi, il ruolo Secret Manager Secret Accessor viene concesso automaticamente al tuo agente di servizio Cloud Build, service-${PROJECT_NUMBER}@gcp-sa-cloudbuild.iam.gserviceaccount.com. Se non vedi questo ruolo aggiunto automaticamente al tuo agente di servizio, completa i passaggi descritti in Concedi il ruolo Secret Manager al service account.
- Origine (facoltativo): se specifichi una configurazione di build incorporata, non è necessario specificare un'origine. In caso contrario, segui questi passaggi:
  - Generazione del repository: seleziona 2ª generazione.
  - Repository: dall'elenco dei repository disponibili, seleziona il repository da cui vuoi eseguire la build. La regione del repository deve corrispondere a quella del trigger.
  - Branch o Tag: specifica un'espressione regolare con il valore del branch o del tag da soddisfare. Per informazioni sulla sintassi accettabile per le espressioni regolari, consulta la sintassi RE2.
  - Controllo dei commenti: se hai selezionato Richiesta di pull come Evento, scegli una delle seguenti opzioni per controllare se il trigger richiama automaticamente una build:
    
    Avviso: qualsiasi utente con accesso in lettura al repository può inviare una richiesta di pull, il che può comportare l'esecuzione di una build che include modifiche al codice sorgente nella richiesta di pull. Per disabilitare questo comportamento, ti consigliamo di utilizzare le approvazioni manuali al fine di limitare le build quando esegui richieste di pull sui repository pubblici. Puoi anche scoprire di più sui privilegi di build dei trigger.
    - Obbligatorio tranne che per proprietari e collaboratori: quando una richiesta di pull viene creata o aggiornata da un proprietario o collaboratore del repository, le build vengono eseguite automaticamente. Se un collaboratore esterno avvia l'azione, le build vengono eseguite solo dopo che un proprietario o un collaboratore commenta /gcbrun sulla richiesta di pull.
    - Obbligatorio: quando una richiesta di pull viene creata o aggiornata da un collaboratore, le build vengono eseguite solo dopo che un proprietario o un collaboratore commenta /gcbrun nella richiesta di pull. Le build vengono eseguite ogni volta che viene apportata una modifica a una richiesta di pull.
    - Non richiesto: quando una richiesta di pull viene creata o aggiornata da un collaboratore, le build vengono eseguite automaticamente.
- 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 origine, devi selezionare un file di configurazione di 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 tua configurazione.
    - Dockerfile: utilizza un Dockerfile per la configurazione.
    - Buildpack: utilizza i buildpack per la tua configurazione.
  - Località: specifica la località per la configurazione.
    - Repository: se il file di configurazione si trova nel repository remoto, specifica la posizione del file di configurazione della build, della directory Dockerfile o della directory dei buildpack. Se il tipo di configurazione di build è Dockerfile o un buildpack, devi fornire un nome per l'immagine risultante e, facoltativamente, un timeout per la build. Dopo aver fornito il nome dell'immagine Dockerfile o del buildpack, vedrai 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 i valori e le variabili di ambiente 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 di compilazione nella consoleGoogle Cloud utilizzando la sintassi YAML o JSON. Fai clic su Fine per salvare la configurazione di build.
      
      Nota: Il supporto per la configurazione di compilazione inline non è disponibile per Dockerfile o buildpack.
  Nell'esempio seguente, i log del file di configurazione di compilazione incorporato mostrano "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 di 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 \
  --trigger-config=TRIGGER_CONFIG_PATH \
  --name=TRIGGER_NAME \
  --description=DESCRIPTION \
  --region=REGION \
  --secret=projects/PROJECT_ID/secrets/SECRET_NAME/versions/SECRET_VERSION \
  --service-account=SERVICE_ACCOUNT \ 
  --repository=projects/PROJECT_ID/locations/REGION/connections/CONNECTION_NAME/repositories/REPO_NAME \ 
  --build-config=PATH_TO_BUILD_CONFIG \
  --inline-config=PATH_TO_INLINE_BUILD_CONFIG \
  --dockerfile=DOCKERFILE \
  --dockerfile-dir=DOCKERFILE_DIR \
  --dockerfile-image=DOCKERFILE_IMAGE \
  --tag=TAG_NAME \
  --branch=BRANCH_NAME \
  --substitutions=_SUB_ONE=SUBSTITUTION \
  --subscription-filter=FILTER \
  --require-approval

Dove:

TRIGGER_CONFIG_PATH è il percorso di un file di configurazione del trigger. Se utilizzi un file di configurazione del trigger, i campi name, description, region, secret, service-account, subscription-filter e substitution devono rimanere non definiti. Per saperne di più, consulta BuildTrigger nella documentazione di riferimento di Cloud Build.
TRIGGER_NAME è il nome del trigger.
DESCRIPTION (Facoltativo) è una descrizione del trigger.
REGION è la regione del trigger. Questo valore deve essere una regione diversa da "global".
SECRET_NAME è il nome del secret archiviato in Secret Manager.
SECRET_VERSION è la versione associata al tuo secret archiviato in Secret Manager.
SERVICE_ACCOUNT è il account di servizio utilizzato per eseguire tutte le operazioni controllate dall'utente relative al trigger di build. Se non definisci un account di servizio, Cloud Build utilizza il service account Cloud Build predefinito.
PROJECT_ID è l'ID progetto Google Cloud .
CONNECTION_NAME è il nome della connessione host.
REPO_NAME è il nome del tuo repository.
PATH_TO_BUILD_CONFIG è il percorso di un file di configurazione di build. Utilizza questo parametro se il trigger fa riferimento a un file di configurazione di build in un repository Cloud Build. Se imposti questo parametro, non puoi definire un inline-config o utilizzare parametri per un Dockerfile.
PATH_TO_INLINE_BUILD_CONFIG è il percorso di una configurazione di build in linea. Utilizza questo parametro se il trigger fa riferimento a un file di configurazione di build locale. Se imposti questo parametro, non puoi definire un build-config o utilizzare parametri per un Dockerfile.
DOCKERFILE è il percorso di un Dockerfile. Utilizza questo parametro se il trigger fa riferimento a un Dockerfile. Se imposti i parametri del Dockerfile, non puoi definire un build-config o un inline-config.
DOCKERFILE_DIR è la directory del Dockerfile.
DOCKERFILE_IMAGE è il nome dell'immagine Docker creata da Cloud Build.
BRANCH_NAME è il nome del tuo branch se vuoi impostare il trigger in modo che venga eseguito su un branch. Se imposti questo parametro, non puoi definire un tag.
TAG_NAME è il nome del tag se vuoi impostare il trigger in modo che venga creato su un tag. Se imposti questo parametro, non puoi definire un branch.
SUBSTITUTION (facoltativo) sono i parametri da sostituire nella specifica di build. Ad esempio, _SUB_ONE='$(body.message.test)',_SUB_TWO='$(body.message.output)'.
(Facoltativo) FILTER è un'espressione di filtro CEL per il trigger, ad esempio '_SUB_ONE == "prod"'.
(Facoltativo) Quando nel comando è presente --require-approval, Cloud Build richiede l'approvazione manuale per le build attivate.

Richiama un evento webhook

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 "{}"

(Facoltativo) Concedi il ruolo Secret Manager al account di servizio

Quando configuri il secret durante la creazione del trigger del webhook, nella maggior parte dei casi Cloud Build concede automaticamente il ruolo Secret Manager Secret Accessor ai service account che lo richiedono. Tuttavia, se utilizzi un secret esistente, potresti anche dover concedere manualmente il ruolo Secret Manager Secret Accessor al tuo account di servizio Cloud Build:

Apri la pagina IAM nella console Google Cloud :

Apri la pagina IAM
(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 console Google Cloud :

Apri la pagina Secret Manager
Fai clic sul nome del secret.

Viene visualizzata la pagina Dettagli secret.
1. Fai clic sulla scheda Autorizzazioni.
2. Fai clic su Concedi l'accesso.
  
  Verrà visualizzato il riquadro Concedi l'accesso.
3. Nella sezione Aggiungi entità, aggiungi l'indirizzo email associato al account di servizio di build.
4. Nella sezione Assegna i ruoli, seleziona Secret Manager > Secret Manager Secret Accessor.
5. Fai clic su Salva.

(Facoltativo) Ottieni una chiave API

Per autenticare un evento webhook in entrata, è necessaria una chiave API. Questa chiave API fa parte del secret che scegli quando configuri il trigger del webhook. Se non hai ancora una chiave API o se Cloud Build non è riuscito a recuperarne una durante la configurazione del secret nella console Google Cloud , puoi creare manualmente una chiave API:

Per ottenere una chiave API:

Apri la pagina Credenziali nella console Google Cloud :

Apri la pagina Credenziali
Fai clic su Crea credenziali.
Fai clic su Chiave API.

Verrà visualizzata una finestra di dialogo con la chiave API creata. Prendi nota della tua 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. In caso contrario, fai clic su Chiudi.

Per scoprire come limitare la chiave, consulta Applicazione delle restrizioni relative alle chiavi API.

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.