Crea e gestisci i trigger di build

Un trigger di Cloud Build avvia automaticamente una build ogni volta che apporti modifiche al codice sorgente. Puoi configurare il trigger in modo da creare il codice per qualsiasi modifica apportata al repository di codice sorgente o solo per le modifiche che soddisfano determinati criteri.

Questa pagina spiega come connettersi ai repository di origine come GitHub e Bitbucket e come creare trigger di build per creare il codice nei repository.

Prima di iniziare

• Attiva l'API Cloud Build.

  Abilita l'API

• Per creare i trigger, devi disporre del ruolo Editor Cloud Build (roles/cloudbuild.builds.editor) nel progetto.
• È necessario un codice sorgente in Cloud Source Repositories, GitHub o Bitbucket.
• Devi avere un Dockerfile o un file di configurazione di Cloud Build.

Connessione ai repository di origine

Devi connettere Cloud Build al repository di codice sorgente prima di creare il codice nel repository. I repository in Cloud Source Repositories sono connessi a Cloud Build per impostazione predefinita. Puoi creare trigger per i tuoi repository direttamente in Cloud Source Repositories senza connetterli manualmente.

Se devi connettere un repository esterno, ad esempio uno ospitato su GitHub o Bitbucket, per connettere inizialmente il repository a Cloud Build dovrai disporre delle autorizzazioni di livello amministratore sul repository. Non sono necessarie autorizzazioni di amministratore per creare trigger in un repository già connesso a Cloud Build.

Completa i seguenti passaggi per connetterti a GitHub o Bitbucket:

1. Apri la pagina Attivatori nella console Google Cloud.

   Apri la pagina Trigger

2. Seleziona il progetto e fai clic su Apri.

3. Seleziona la regione in cui vuoi creare il trigger dal menu a discesa Regione.

   Nota: se selezioni global come regione, i pool predefiniti vengono utilizzati per eseguire la build. In caso contrario, per eseguire la build viene utilizzato un pool privato nella regione del trigger. Devi specificare il pool privato nel file di configurazione della build o tramite argomenti di build.

4. Fai clic su Connetti repository.

5. Seleziona il repository in cui hai archiviato il codice sorgente.

   Se selezioni GitHub (con mirroring) o Bitbucket (con mirroring) come repository di codice sorgente, Cloud Build esegue il mirroring del tuo repository in Cloud Source Repositories e utilizza il repository con mirroring per tutte le sue operazioni.

6. Fai clic su Continua.

7. Esegui l'autenticazione nel repository di codice sorgente con il tuo nome utente e la tua password.

8. Dall'elenco dei repository disponibili, seleziona quello desiderato e fai clic su Connetti.

   Per i repository esterni, come GitHub e Bitbucket, devi disporre delle autorizzazioni a livello di proprietario per il progetto Google Cloud con cui stai lavorando.

9. Fai clic su Crea un trigger per continuare a creare un trigger di build per automatizzare le build per il codice sorgente nel repository oppure fai clic su Fine.

Creazione di un trigger di build

Console

1. Apri la pagina Attivatori nella console Google Cloud.

   Apri la pagina Attivatori

2. Seleziona il progetto dal menu a discesa del selettore di progetti nella parte superiore della pagina.

3. Fai clic su Apri.

4. Fai clic su Crea trigger.

5. Inserisci le seguenti impostazioni di attivazione:

   • Nome: inserisci un nome per l'attivatore.

   • Regione: seleziona la regione per l'attivatore.

     Se il file di configurazione della build associato al trigger specifica un pool privato, la regione selezionata per il trigger deve corrispondere a quella del pool privato.

     Se selezioni global come regione, Cloud Build utilizza la regione specificata nel file di configurazione della build per eseguire la build. Può essere la regione del pool privato, se specifichi un pool privato nel file di configurazione della build, o il pool predefinito globale se non specifichi un pool privato.

   • (Facoltativo) Descrizione: inserisci una descrizione per l'attivatore.

   • Evento: seleziona l'evento del repository per richiamare il trigger.

     • Push al ramo: imposta il trigger per avviare una build sui commit in un ramo specifico.

     • Esegui il push del nuovo tag: imposta l'attivatore in modo che avvii una build sui commit che contengono un determinato tag.

     • Richiesta di pull: imposta il trigger per avviare una build sui commit in una richiesta di pull.

       Nota: a prescindere che siano basate su commit di ramo o commit di tag, le build vengono richiamate solo in caso di push all'origine remota, non in caso di modifiche locali, pre-invii o richieste di pull.

   • Origine: seleziona 1a generazione o 2a generazione come origine. Puoi connettere repository solo da GitHub e GitHub Enterprise se selezioni 2a generazione come origine. Per saperne di più, consulta Repository Cloud Build.

     Nota: la regione del repository deve corrispondere a quella del trigger. Se l'origine è un repository di codice sorgente Cloud, il repository non è connesso a una determinata regione, ma al tuo progetto.
     • Repository: dall'elenco dei repository disponibili, seleziona il repository desiderato. Per connettere un nuovo repository, consulta Connessione ai repository di origine.
     Nota: se rinomini il repository dopo la creazione del trigger, devi aggiornare manualmente il nome del repository nel trigger. Attualmente, Cloud Build non reindirizza automaticamente le richieste di build dal trigger se il nome di un repository viene aggiornato.

     • Ramo o Tag: specifica un'espressione regolare con il valore del ramo o del tag da associare. Nei tag non è possibile utilizzare le barre (/). Per ulteriori informazioni sulla sintassi accettabile delle espressioni regolari, consulta la sezione sintassi RE2.

       All'esecuzione della build, Cloud Build copia i contenuti del repository in /workspace, la directory di lavoro predefinita per Cloud Build. Scopri di più sulle directory di lavoro nella pagina Panoramica della configurazione di creazione.

       Per consentire solo le build da origini specifiche, imposta un criterio dell'organizzazione per le integrazioni consentite (constraints/cloudbuild.allowedIntegrations) in modo da negare l'interazione con l'origine definita nel trigger. Il criterio dell'organizzazione sostituisce il trigger e la build non viene eseguita. Per saperne di più, consulta la sezione Gate si basa sul criterio dell'organizzazione per il tuo progetto.

   • File inclusi (facoltativo): le modifiche che interessano almeno uno di questi file richiamano una build. Puoi utilizzare le stringhe glob per specificare più file con caratteri jolly. I caratteri jolly accettabili includono quelli supportati da Go Match, ** e alternanza.

     Nota: ** è una versione ricorsiva di * che corrisponde a tutti i file e le directory nella directory selezionata e nelle relative sottodirectory. Ad esempio, il pattern src/* corrisponderà a src/code.py, ma ignorerà src/sub/code.py mentre src/** corrisponderà a entrambi.

   • File ignorati (facoltativo): le modifiche che interessano solo i file ignorati non richiamano una build. Puoi usare le stringhe glob per specificare più file con caratteri jolly. I caratteri jolly accettabili includono i caratteri supportati da Go Match, ** e alternanza.

     Nota: le stringhe globb non consentono variabili di sostituzione nei file inclusi e ignorati.

     Se specifichi un file sia in File inclusi sia in File ignorati, le modifiche a quel file non richiamano una build. Supponiamo di specificare **/README.md in File ignorati per ignorare README.md in qualsiasi directory e di specificare src/* in File inclusi per avviare una build in caso di modifiche a qualsiasi file nella cartella src/. Ora, se apporti una modifica a src/README.md, Cloud Build non avvierà una build. Ogni volta che esegui il push di una modifica all'origine, Cloud Build analizza i file modificati per individuare i file inclusi e ignorati per stabilire se una build deve essere richiamata:

     • Se esegui il push di una modifica nel repository su un ramo esistente, Cloud Build controlla i file modificati tra il commit di cui hai appena eseguito il push e il commit a cui il ramo rimandava in precedenza.
     • Se il tuo repository è Cloud Source Repository e invii una modifica a un ramo appena creato, Cloud Build tratta tutti i file nel repository come file modificati.
     • Se elimini un ramo, Cloud Build non avvia una build.
   Nota: i valori File inclusi e File ignorati possono essere specificati solo se selezioni Invia a un ramo o Esegui il push di nuovo tag come Evento.

   • Configurazione: seleziona il file di configurazione della build che si trova nel repository remoto o crea un file di configurazione di compilazione incorporato da utilizzare per la build.

     • 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 buildpacks per la configurazione.

     • Posizione: specifica la località 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 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 dalla tua build.
       • Variabili di ambiente Buildpack (facoltativo). Se hai selezionato buildpacks come tipo di configurazione, fai clic su Aggiungi variabile di ambiente buildpack per specificare le variabili e i valori di ambiente del buildpack. Per scoprire di più sulle variabili di ambiente 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 console Google Cloud utilizzando la sintassi YAML o JSON. Fai clic su Fine per salvare la configurazione della build.

         Nota: il supporto per la configurazione della build in linea non è disponibile per Dockerfile o per buildpack.

   • Utilizza pool privato: questo campo viene visualizzato se hai selezionato Dockerfile come opzione di configurazione. Seleziona questa casella di controllo se esegui la build in un pool privato.

   • Pool privato: se hai selezionato Utilizza pool privato, specifica il nome della risorsa per il pool privato nel modulo projects/WORKERPOOL_PROJECT_ID/locations/REGION/workerPools/WORKERPOOL_ID.

   • Variabili di sostituzione (facoltativo): se hai selezionato il file di configurazione di Cloud Build come opzione di configurazione della build, puoi scegliere di definire variabili di sostituzione specifiche del trigger utilizzando questo campo. Ad esempio, supponiamo che tu stia creando più trigger in cui ogni trigger esegue il deployment della tua app in un ambiente specifico. Puoi specificare che il deployment dell'app è stato eseguito in un ambiente nel file di configurazione della build, quindi utilizzare questo campo per definire le variabili di sostituzione che specificano in quale ambiente deve essere eseguito il deployment di questo trigger. Per informazioni su come specificare i valori di sostituzione nei file di configurazione della build, consulta Sostituzione dei valori delle variabili.

   • (Facoltativo) Approvazione: seleziona la casella per richiedere l'approvazione prima dell'esecuzione della build.

   • Account di servizio: seleziona l'account di servizio da utilizzare quando richiami il trigger. Se non selezioni un account di servizio, viene utilizzato l'account di servizio Cloud Build predefinito.

     Nota: per le build eseguite dai trigger verrà utilizzato solo l'account di servizio specificato nel trigger. Se hai specificato un account di servizio nella configurazione della build, questo verrà ignorato durante l'esecuzione della build quando utilizzi i trigger.

6. Fai clic su Crea per salvare il trigger di build.

gcloud

Per creare un trigger se il codice sorgente si trova in Cloud Source Repositories:

    gcloud builds triggers create cloud-source-repositories \
    --repo=REPO_NAME \
    --branch-pattern=BRANCH_PATTERN \ # or --tag-pattern=TAG_PATTERN
    --build-config=BUILD_CONFIG_FILE \
    --service-account=SERVICE_ACCOUNT \
    --require-approval

Dove:

• REPO_NAME è il nome del repository.
• BRANCH_PATTERN è il nome del ramo nel repository per richiamare la build.
• TAG_PATTERN è il nome del tag nel repository per richiamare la build.

• BUILD_CONFIG_FILE è il percorso del file di configurazione della build.

• SERVICE_ACCOUNT è l'indirizzo email associato al tuo account di servizio. Se non includi questo flag, viene utilizzato l'account di servizio Cloud Build predefinito.

Nota: per le build richiamate con i trigger viene utilizzato solo l'account di servizio specificato nel comando gcloud builds triggers create. I trigger di build ignorano l'account di servizio specificato nel file di configurazione della build.

• [Facoltativo] --require-approval è il flag da includere per configurare l'attivatore in modo che richieda l'approvazione.

Per un elenco completo dei flag, consulta il riferimento gcloud su come creare trigger per Cloud Source Repositories.

Per creare un trigger se il tuo codice sorgente è in GitHub:

    gcloud builds triggers create github \
    --region=REGION \
    --repo-name=REPO_NAME \
    --repo-owner=REPO_OWNER \
    --branch-pattern=BRANCH_PATTERN \ # or --tag-pattern=TAG_PATTERN
    --build-config=BUILD_CONFIG_FILE \
    --service-account=SERVICE_ACCOUNT \
    --require-approval
    --include-logs-with-status

Dove:

• REGION è la regione per il trigger.
• REPO_NAME è il nome del repository.
• REPO_OWNER è il nome utente del proprietario del repository.
• BRANCH_PATTERN è il nome del ramo nel repository per richiamare la build.
• TAG_PATTERN è il nome del tag nel repository per richiamare la build.
• BUILD_CONFIG_FILE è il percorso del file di configurazione della build.
• SERVICE_ACCOUNT è l'indirizzo email associato al tuo account di servizio. Se non includi questo flag, viene utilizzato l'account di servizio Cloud Build predefinito.
• [Facoltativo] --require-approval è il flag da includere per configurare l'attivatore in modo che richieda l'approvazione.
• [Facoltativo] --include-logs-with-status è un flag che puoi specificare per mostrare i log di build dei repository. Questo flag è supportato per le build dei repository GitHub e GitHub Enterprise.

Nota: puoi utilizzare il flag --include-logs-with-status solo quando crei un trigger GitHub o GitHub Enterprise utilizzando gcloud. Al momento Cloud Build non supporta la funzionalità per la creazione di un trigger utilizzando la console Google Cloud.

Per un elenco completo dei flag, consulta la documentazione di riferimento gcloud su come creare trigger per GitHub.

Dopo aver eseguito il comando gcloud per creare un trigger utilizzando Cloud Source Repositories o GitHub, dovresti vedere un output simile al seguente:

  NAME         CREATE_TIME                STATUS
  trigger-001  2019-10-30T20:45:03+00:00

Nota: il nome dell'attivatore viene generato automaticamente. Puoi modificare il nome del trigger tramite la console Google Cloud.

Test di un trigger di build

Per testare manualmente un trigger di build:

1. Apri la pagina Attivatori nella console Google Cloud.

   Apri la pagina Trigger

2. Individua il trigger nell'elenco e fai clic su Esegui trigger.

Ignorare un trigger di build

In alcuni casi, potresti voler apportare una modifica al codice sorgente, ma non vuoi richiamare una build. Ad esempio, potresti non voler richiamare una build quando aggiorni la documentazione o i file di configurazione.

In questi scenari, puoi includere [skip ci] o [ci skip] nel messaggio di commit e non verrà richiamata una build.

Se vuoi eseguire una build su quel commit in un secondo momento, utilizza il pulsante Esegui trigger nella pagina Trigger.

Inclusione della cronologia del repository in una build

Per creare il codice sorgente su un repository Git, Cloud Build esegue un clone superficiale del repository. Ciò significa che nell'area di lavoro da creare viene eseguito il check-out del singolo commit che ha avviato la build. Cloud Build non verifica nessun altro ramo o cronologia. Questo viene fatto per garantire l'efficienza, in modo che le build non debbano attendere per recuperare l'intero repository e la cronologia solo per creare un singolo commit.

Se vuoi includere una quantità maggiore della cronologia del repository nella build, aggiungi un passaggio di build nel file di configurazione della build per eliminare il clone. Ad esempio:

steps:
- name: gcr.io/cloud-builders/git
  args: ['fetch', '--unshallow']
...

Nota: se l'origine si trova in un repository Git privato, dovrai archiviare le tue credenziali in modo sicuro utilizzando Secret Manager per accedere ai comandi git, come il comando riportato sopra per annullare la rimozione del clone del repository. Per ulteriori istruzioni, vedi Accesso ai repository privati GitHub.

Per ulteriori informazioni su git fetch, consulta il riferimento git. Per istruzioni sulla scrittura di un file di configurazione della build, consulta Panoramica della configurazione di build.

Reinvio di una build per l'approvazione

Se la build è stata rifiutata, puoi inviarla nuovamente per l'approvazione seguendo questi passaggi nella console Google Cloud:

1. Apri la pagina Cronologia di Cloud Build nella console Google Cloud.

   Apri la pagina Cronologia di Cloud Build

2. Fai clic sull'ID build della build che vuoi inviare nuovamente per l'approvazione.

3. Fai clic su Ricrea nella parte superiore della pagina per inviare nuovamente la build per l'approvazione.

La tua build verrà avviata quando un utente con le autorizzazioni la approverà. Per scoprire di più sulle approvazioni di Cloud Build, consulta Le build di gateway all'approvazione.

Aggiornamento di un trigger di build

Console

1. Apri la pagina Attivatori nella console Google Cloud.

   Apri la pagina Trigger di build

2. Seleziona il progetto dal menu a discesa del selettore di progetti nella parte superiore della pagina.

3. Fai clic su Apri.

4. Individua la riga con l'attivatore da aggiornare.

5. Fai clic sul menu (i puntini di sospensione verticali) che si trova all'estremità destra della riga.

6. Seleziona Modifica.

Nota: puoi aggiornare tutti i campi associati al trigger utilizzando la console Google Cloud, tranne la visualizzazione dei log di build. Consulta le gcloud istruzioni su come aggiornare un trigger di build per mostrare o nascondere i log di build per i trigger GitHub o GitHub Enterprise.

gcloud

Per aggiornare un attivatore:

1. Esporta l'attivatore che vuoi aggiornare:

    gcloud builds triggers export TRIGGER_NAME --destination=EXPORT_PATH
   

   Dove:

   • TRIGGER_NAME è il nome dell'attivatore.
   • EXPORT_PATH è il percorso file in cui vuoi esportare il trigger. Ad esempio, puoi specificare il percorso file come examples/trigger.yaml. Tieni presente che il nome file del trigger deve avere l'estensione .yaml.

2. Apri il file contenente l'attivatore esportato.

   Il file sarà simile al seguente:

    createTime: '2022-05-26T21:56:11.830784153Z'
    filename: cloudbuild.yaml
    github:
      name: cloud-build-example
      owner: main
      push:
        branch: master
    id: 86201062-3b14-4b6a-a2fb-4ee924e8b1dd
    # remove field name and value to not show build logs
    includeBuildLogs: INCLUDE_BUILD_LOGS_WITH_STATUS
    name: trigger-001
   

3. Modifica manualmente il file per aggiornare l'attivatore.

   Per visualizzare i campi che puoi aggiungere o rimuovere dall'attivatore, consulta la risorsa trigger.

4. Salva il file.

5. Importa l'attivatore:

    gcloud builds triggers import --source=IMPORT_PATH
   

   Dove:

   • IMPORT_PATH è il percorso file dell'attivatore che vuoi importare.

Il trigger di build è stato aggiornato.

Disabilitazione di un trigger di build

Console

1. Apri la pagina Attivatori nella console Google Cloud.

   Apri la pagina Trigger di build

2. Seleziona il progetto dal menu a discesa del selettore di progetti nella parte superiore della pagina.

3. Fai clic su Apri.

4. Individua la riga con l'attivatore da disabilitare.

5. Fai clic sul menu (i puntini di sospensione verticali) che si trova all'estremità destra della riga.

6. Seleziona Disable (Disattiva).

gcloud

Per disattivare un attivatore:

1. Esporta l'attivatore che vuoi disabilitare:

    gcloud builds triggers export TRIGGER_NAME --destination=EXPORT_PATH
   

   Dove:

   • TRIGGER_NAME è il nome dell'attivatore.
   • EXPORT_PATH è il percorso file in cui vuoi esportare il trigger. Ad esempio, puoi specificare il percorso file come examples/trigger.yaml. Tieni presente che il nome file del trigger deve avere l'estensione .yaml.

2. Apri il file contenente l'attivatore esportato.

   Il file sarà simile al seguente:

    createTime: '2020-02-21T20:02:50.215599013Z'
    description: Push to any branch
    filename: cloudbuild.yaml
    github:
      name: example-repo-name
      owner: example-owner
      push:
        branch: .*
    id: example-id
    name: Push-to-any-branch
    tags:
    - github-default-push-trigger
   

3. Aggiungi il campo disabled alla fine del file e imposta il valore su True.

    disabled: True
   

4. Salva il file.

5. Importa l'attivatore:

    gcloud builds triggers import --source=IMPORT_PATH
   

   Dove:

   • IMPORT_PATH è il percorso file dell'attivatore che vuoi importare.

Il trigger di build è ora disattivato.

Nota: la disabilitazione di un trigger mediante i comandi gcloud potrebbe non funzionare se al trigger non è associato un file di configurazione della build.

La disabilitazione di un trigger non lo elimina. Per eliminare un trigger, consulta Eliminazione di un trigger di build. Un attivatore può essere riattivato modificando lo stato in Attivato.

Eliminazione di un trigger di build

Console

1. Apri la pagina Attivatori nella console Google Cloud.

   Apri la pagina Trigger di build

2. Seleziona il progetto dal menu a discesa del selettore di progetti nella parte superiore della pagina.

3. Fai clic su Apri.

4. Individua la riga con l'attivatore da eliminare.

5. Fai clic sul menu (i puntini di sospensione verticali) che si trova all'estremità destra della riga.

6. Seleziona Elimina.

gcloud

Per eliminare un trigger, esegui questo comando:

  gcloud builds triggers delete TRIGGER_NAME

Dove:

• TRIGGER_NAME è il nome dell'attivatore.

Per un elenco completo dei flag, consulta il riferimento gcloud su come eliminare gli attivatori.

Implicazioni per la sicurezza dei trigger di build

Nota: per migliorare la strategia di sicurezza predefinita dei tuoi progetti, Cloud Build introdurrà alcune modifiche che richiederanno di selezionare esplicitamente un account di servizio quando crei un trigger nei nuovi progetti. Per maggiori informazioni, consulta Modifica dell'account di servizio Cloud Build.

Per impostazione predefinita, i trigger di build utilizzano l'account di servizio Cloud Build per eseguire le build, il che potrebbe fornire autorizzazioni in fase di build agli utenti che utilizzano i trigger per eseguire una build. Quando utilizzi i trigger di build, tieni presente le seguenti implicazioni per la sicurezza:

• Un utente che non ha accesso al progetto Cloud, ma con accesso in scrittura al repository associato ai trigger di build nel progetto, avrà le autorizzazioni per modificare il codice in fase di creazione.
• Se utilizzi i trigger delle richieste di pull GitHub, qualsiasi utente con accesso in lettura al repository può inviare una richiesta di pull, che può eseguire una build che include modifiche al codice nella richiesta di pull. Per informazioni su come disabilitare questo comportamento per i trigger delle richieste di pull GitHub, consulta Creazione dei trigger di GitHub.

È buona norma creare un account di servizio con solo i ruoli richiesti per il trigger. Per scoprire di più, consulta Configurare gli account di servizio specificati dall'utente. Per saperne di più sull'account di servizio Cloud Build e sulle autorizzazioni associate, vedi Account di servizio Cloud Build.

Passaggi successivi

• Scopri come avviare manualmente le build o configurare deployment che richiedono chiamate manuali creando manualmente il codice nei repository di origine.
• Scopri come creare trigger GitHub.
• Scopri come automatizzare le build in risposta agli eventi Pub/Sub.
• Scopri come automatizzare le build in risposta agli eventi webhook.
• Scopri come visualizzare i risultati della build per i trigger di build.
• Scopri come eseguire deployment blu/verde su Compute Engine.
• Scopri come risolvere gli errori di generazione.