Connettersi a Cloud Build

Questa pagina descrive in dettaglio come richiamare automaticamente le build da Secure Source Manager utilizzando i file di configurazione di Cloud Build e un file YAML dei trigger nel repository Secure Source Manager.

Per impostazione predefinita, Secure Source Manager utilizza un service agent gestito da Google per interagire con Cloud Build e altre risorse. Per isolare le autorizzazioni del team, ti consigliamo di configurare un'identità per repository associando un service account gestito dall'utente al repository. Secure Source Manager utilizza il account di servizio gestito dall'utente associato al repository per attivare le build.

A differenza del service agent predefinito, puoi configurare un account di servizio gestito dall'utente con l'autorizzazione iam.serviceAccounts.actAs sui service account Cloud Build personalizzati. In questo modo puoi eseguire le build utilizzando service account personalizzati, mantenendo le autorizzazioni di build limitate a quel repository.

Prima di iniziare

1. Crea un'istanza Secure Source Manager.
2. Crea un repository Secure Source Manager.

3. Configura un service account Cloud Build specificato dall'utente. Per consentire a Cloud Build di leggere dal repository Secure Source Manager, concedi al account di servizio Cloud Build (il service account predefinito o un service account gestito dall'utente) i seguenti ruoli:

   • Secure Source Manager Instance Accessor (roles/securesourcemanager.instanceAccessor) sull'istanza Secure Source Manager.
   • Secure Source Manager Repository Reader sul repository.

   A seconda del caso d'uso, il account di servizio Cloud Build potrebbe richiedere ruoli aggiuntivi, ad esempio:

   • Per archiviare i log di build in Cloud Logging, concedi il ruolo Writer log (roles/logging.logWriter) al account di servizio Cloud Build.
   • Per accedere ai secret in Secret Manager, concedi il ruolo Secret Manager Secret Accessor (roles/secretmanager.secretAccessor) al account di servizio Cloud Build.

   Per informazioni sui log di build, consulta Configurare i log di build.

4. Se le build vengono eseguite nei pool di worker, concedi al account di servizio gestito dall'utente del repository il ruolo Cloud Build WorkerPool User (roles/cloudbuild.workerPoolUser) nel progetto in cui vengono eseguite le build.

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per connettere un repository Secure Source Manager a Cloud Build, chiedi all'amministratore di concederti i seguenti ruoli IAM:

• Secure Source Manager Repository Writer (roles/securesourcemanager.repoWriter) sul repository
• Secure Source Manager Instance Accessor (roles/securesourcemanager.instanceAccessor) sull'istanza Secure Source Manager

Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

Per informazioni sulla concessione dei ruoli Secure Source Manager, consulta Controllo dell'accesso con IAM e Concedi agli utenti l'accesso all'istanza.

Ruoli del account di servizio obbligatori

Per connettere Secure Source Manager a Cloud Build, devi configurare le autorizzazioni IAM per un'identità per repository.

Configurazione dell'identità per repository

Per utilizzare un'identità per repository, devi configurare le autorizzazioni.

Nota: per impostazione predefinita, puoi utilizzare solo un account di servizio gestito dall'utente che si trova nello stesso Google Cloud progetto del repository e delle build. Se il account di servizio gestito dall'utente si trova in un progetto diverso (configurazione tra progetti), devi disabilitare il vincolo della policy dell'organizzazione iam.disableCrossProjectServiceAccountUsage nel progetto in cui si trova il account di servizio gestito dall'utente. Per ulteriori informazioni, consulta Configurazione del account di servizio tra progetti.

1. Utente: l'utente che configura il service account del repository deve avere il ruolo Utente account di servizio (roles/iam.serviceAccountUser) sul service account gestito dall'utente. Questa autorizzazione viene verificata durante la creazione o l'aggiornamento del repository.

2. Service agent Secure Source Manager: concedi al service agent Secure Source Manager per il progetto del repository il ruolo Creatore token account di servizio (roles/iam.serviceAccountTokenCreator) sul service account gestito dall'utente.

   L'indirizzo email del service agent Secure Source Manager ha il formato [e-mail], dove REPOSITORY_PROJECT_NUMBER è il numero del progetto che ospita il repository.

3. Service account gestito dall'utente:

   • Concedi al service account gestito dall'utente il ruolo Utente account di servizio (roles/iam.serviceAccountUser) sul service account Cloud Build personalizzato (nel progetto del repository).
   • Concedi al account di servizio gestito dall'utente il ruolo Editor Cloud Build (roles/cloudbuild.builds.editor) e il ruolo Consumer utilizzo servizi (roles/serviceusage.serviceUsageConsumer) nel progetto in cui vengono eseguite le build.

Per informazioni su come concedere i ruoli IAM, consulta Concedere o revocare un singolo ruolo.

Crea un file di configurazione di compilazione

Un file di configurazione di compilazione definisce i campi necessari a Cloud Build per eseguire le attività di compilazione. Puoi scrivere il file di configurazione di compilazione utilizzando la sintassi YAML.

Puoi creare file di configurazione di compilazione nel branch o nei branch da cui vuoi eseguire la compilazione.

Per creare un file di configurazione di compilazione:

1. Nell'interfaccia web di Secure Source Manager, seleziona il repository che vuoi connettere a Cloud Build.
2. Seleziona il branch da cui vuoi eseguire la compilazione utilizzando Cloud Build.

3. Crea un file di configurazione di compilazione. Per informazioni su come creare file di configurazione di compilazione, segui le istruzioni riportate in Crea un file di configurazione di compilazione.

4. Esegui il commit delle modifiche nel branch.

Crea un file dei trigger

Il file di configurazione dei trigger deve essere creato nel branch predefinito del repository.

Per creare un file di configurazione dei trigger:

1. Nel repository locale o nell'interfaccia web di Secure Source Manager, passa al branch predefinito.

2. Crea un file denominato .cloudbuild/triggers.yaml.

3. Configura il trigger nel file .cloudbuild/triggers.yaml:

   triggers:
   - name: TRIGGER_NAME
     project: PROJECT_ID
     configFilePath: CLOUD_BUILD_CONFIG_PATH
     eventType: EVENT_TYPE
     ignoredGitRefs: IGNORED_GIT_REFS
     includedGitRefs: INCLUDED_GIT_REFS
     serviceAccount: SERVICE_ACCOUNT
     includedFiles: INCLUDED_FILES
     ignoredFiles: IGNORED_FILES
     disabled: DISABLED_BOOL
     substitutions:
       _VARIABLE_NAME: VARIABLE_VALUE
       OVERRIDE_VARIABLE_NAME: OVERRIDE_VARIABLE_VALUE
   

   Sostituisci quanto segue:

   • TRIGGER_NAME con un nome per il trigger. I nomi dei trigger possono contenere solo caratteri alfanumerici e trattini e non possono iniziare o terminare con un trattino. I nomi dei trigger devono avere una lunghezza inferiore a 64 caratteri.
   • PROJECT_ID con l' Google Cloud ID del progetto in cui hai abilitato Cloud Build. Questo campo è facoltativo. Il valore predefinito è il progetto Secure Source Manager.
   • CLOUD_BUILD_CONFIG_PATH con il percorso del file di configurazione di Cloud Build che vuoi utilizzare per questo trigger. Questo campo è facoltativo. Il valore predefinito è .cloudbuild/cloudbuild.yaml

   • EVENT_TYPE con il tipo di evento che vuoi attivare per la build. Le opzioni sono le seguenti:

     • push per attivare il push ai branch specificati
     • pull_request per attivare una richiesta di pull ai branch specificati

     Questo campo è facoltativo. Il valore predefinito è push.

   • INCLUDED_GIT_REFS con un'espressione regolare RE2 facoltativa che corrisponde ai riferimenti Git che vuoi attivare per una build. Il valore predefinito è vuoto. Un valore vuoto indica che non ci sono restrizioni.

   • IGNORED_GIT_REFS con un'espressione regolare facoltativa che utilizza il formato dell'espressione regolare RE2 che corrisponde ai riferimenti Git che non vuoi attivare per una build. Il valore predefinito è vuoto. Un valore vuoto indica che non ci sono restrizioni. Il campo ignoredGitRefs viene controllato prima del campo includedGitRefs. Per ulteriori informazioni su questi campi, consulta Schema del file dei trigger.

   • SERVICE_ACCOUNT con il account di servizio Cloud Build da utilizzare per la build nel formato projects/PROJECT_ID/serviceAccounts/ACCOUNT. Sostituisci ACCOUNT con l'indirizzo email o l'ID univoco del account di servizio. Puoi utilizzare il service account Cloud Build predefinito o un service account gestito dall'utente. Il account di servizio Cloud Build legacy non può essere utilizzato a causa delle sue limitazioni.

   • INCLUDED_FILES con un'espressione regolare facoltativa in formato RE2 che corrisponde ai file che vuoi attivare per una build.

     Se uno dei file modificati non corrisponde al campo del filtro ignoredFiles e i file modificati corrispondono al campo del filtro includedFiles, viene attivata una build. Il valore predefinito è vuoto. Un valore vuoto indica che non ci sono restrizioni.

   • IGNORED_FILES con un'espressione regolare facoltativa in formato RE2 che corrisponde ai file che non vuoi attivare per una build.

     Se tutti i file modificati in un commit corrispondono a questo campo del filtro, non viene attivata una build. Il valore predefinito è vuoto. Un valore vuoto indica che non ci sono restrizioni.

   • DISABLED_BOOL con true per disabilitare il trigger o false per abilitare il trigger. Questo campo è facoltativo. Il valore predefinito è false.

   • VARIABLE_NAME con il nome di una variabile che vuoi introdurre nel file dei trigger.

   • VARIABLE_VALUE con il valore della variabile.

   • OVERRIDE_VARIABLE_NAME con il nome della variabile di sostituzione predefinita di Secure Source Manager. Per informazioni sulle variabili di sostituzione predefinite disponibili, consulta la sezione sostituzioni di Schema del file dei trigger.

   • OVERRIDE_VARIABLE_VALUE con il valore con cui vuoi sostituire il valore predefinito della variabile di sostituzione predefinita.

4. Esegui il commit del file di configurazione dei trigger nel branch predefinito.

   Dopo aver eseguito il commit del file dei trigger, Secure Source Manager attiva le build in base alla configurazione nel file dei trigger.

   Secure Source Manager legge i file di configurazione e lo SHA del commit o il riferimento Git associato dei seguenti tipi di eventi:

   • Per gli eventi push, Secure Source Manager leggerà lo SHA del commit o il riferimento Git al termine del push.
   • Per gli eventi pull_request, Secure Source Manager leggerà lo SHA del commit o il riferimento Git da cui vengono estratte le modifiche della richiesta di pull.

Visualizza lo stato della build

Quando una build viene attivata da un evento push o pull request, lo stato del commit e della build viene visualizzato nell'interfaccia web di Secure Source Manager.

I valori possibili per lo stato della build sono i seguenti:

• SUCCESS: la build è stata completata correttamente.
• WARNING: si è verificato un problema durante il tentativo di compilazione.
• FAILURE: la build non è riuscita durante l'esecuzione.

Puoi impedire l'unione dei commit con build non riuscite in branch importanti se configuri una regola di protezione del branch in modo che richieda un controllo dello stato riuscito dai trigger configurati nel file dei trigger. Per saperne di più sulla protezione dei branch, consulta la Panoramica sulla protezione dei branch.

Per visualizzare lo stato della build per un evento push:

1. Nell'interfaccia web di Secure Source Manager, vai al repository.

   Se l'evento push più recente ha attivato una build, lo stato viene visualizzato accanto allo SHA del commit. Per visualizzare i dettagli sullo stato, fai clic sullo stato.

2. Per visualizzare lo stato della build per i commit precedenti, seleziona Commit per visualizzare la cronologia dei commit, quindi fai clic sullo stato di cui vuoi visualizzare i dettagli.

Per visualizzare lo stato della build per un evento pull request:

1. Nell'interfaccia web di Secure Source Manager, fai clic su Pull request.

2. Fai clic sulla pull request che vuoi visualizzare.

   Se le build sono state attivate dalla pull request, vedrai una sezione intitolata o Tutti i controlli sono riusciti o Alcuni controlli hanno segnalato avvisi.

Risoluzione dei problemi

Per trovare metodi per diagnosticare e risolvere gli errori di Cloud Build durante la connessione a Secure Source Manager, consulta Il file dei trigger non attiva la build.

Passaggi successivi

• Scopri come visualizzare i risultati della build in Cloud Build.
• Scopri come risolvere gli errori di build.