Connettiti a un repository GitHub

Questa pagina spiega come connettere un repository GitHub a Cloud Build. Per saperne di più sui repository Cloud Build, consulta Repository Cloud Build.

Prima di iniziare

Abilita le API Cloud Build and Secret Manager.
Abilita le API

Tieni a portata di mano il codice sorgente in un repository GitHub.
Assicurati di avere un Dockerfile o un file di configurazione di Cloud Build nel repository di codice sorgente GitHub.
Se inizialmente connetti il repository a Cloud Build, assicurati di disporre delle autorizzazioni a livello di amministratore sul repository. Per scoprire di più sulle autorizzazioni per i repository GitHub, vedi Livelli di autorizzazione per i repository per un'organizzazione.
Per utilizzare i comandi gcloud in questa pagina, installa Google Cloud CLI.

Nota: se hai già installato gcloud CLI, assicurati di disporre dell'ultima versione disponibile eseguendo gcloud components update.

Connessione di un host GitHub

Console

Per connettere il tuo repository GitHub a Cloud Build:

Apri la pagina Repositories nella console Google Cloud.

Apri la pagina Repository

Verrà visualizzata la pagina Repositories.
Nel selettore dei progetti nella barra superiore, seleziona il tuo progetto Google Cloud.
Nella parte superiore della pagina, seleziona la scheda 2a generazione.
Fai clic su Crea connessione host per connettere un nuovo host a Cloud Build.
Nel riquadro a sinistra, seleziona GitHub come fornitore di origine.
Nella sezione Configura connessione, inserisci le informazioni seguenti:
1. Regione: seleziona una regione per la connessione.
  
  Nota: devi specificare una regione. La connessione non può esistere a livello globale.
2. Nome: inserisci un nome per la connessione,
Fai clic su Connetti.

Dopo aver fatto clic sul pulsante Connetti, ti verrà chiesto di autorizzare l'app GitHub di Cloud Build ad accedere al tuo account GitHub. Puoi revocare l'accesso all'app disinstallando o eliminando l'app dal tuo host in qualsiasi momento.

Cloud Build richiede l'autorizzazione del tuo account utente GitHub e archivia il token di autorizzazione risultante come secret in Secret Manager nel tuo progetto. Il token di autorizzazione viene utilizzato per convalidare l'accesso al tuo account utente per l'installazione dell'app GitHub di Cloud Build e ai repository collegati. L'account dell'agente di servizio Cloud Build (service-{projectNumber}@gcp-sa-cloudbuild.iam.gserviceaccount.com) viene utilizzato per accedere al secret. Per visualizzare il secret, consulta Elencare i secret e visualizzare i dettagli del secret.

Nota: questa autenticazione può essere utilizzata per creare connessioni aggiuntive nello stesso progetto. Per proteggere le connessioni, consigliamo di utilizzare un account robot o un account condiviso dal tuo team, anziché un account GitHub personale.

Dopo aver autorizzato l'app GitHub di Cloud Build, verrà visualizzata la pagina Repositories di Cloud Build.

Hai creato una connessione GitHub.

gcloud

Per connettere l'host GitHub utilizzando gcloud, completa i seguenti passaggi:

Inserisci il comando seguente per avviare una connessione al tuo repository GitHub:
```
 gcloud builds connections create github CONNECTION_NAME --region=REGION
```
Dove:
- CONNECTION_NAME è il nome della tua connessione.
- REGION è la regione per il trigger.
  
  Nota: devi specificare una regione. La connessione non può esistere a livello globale.
Dopo aver eseguito il comando gcloud builds connections, verrà visualizzato un link per autorizzare l'app GitHub di Cloud Build.
Accedi al tuo account github.com.

Nota: questa autenticazione può essere utilizzata per creare connessioni aggiuntive nello stesso progetto. Per proteggere le connessioni, consigliamo di utilizzare un account robot o un account condiviso dal tuo team, anziché un account GitHub personale.
Segui il link per autorizzare l'app GitHub di Cloud Build.

Dopo aver autorizzato l'app, Cloud Build archivia un token di autenticazione come secret in Secret Manager nel tuo progetto Google Cloud. Puoi visualizzare i tuoi secret nella pagina Secret Manager.
Installa l'app GitHub di Cloud Build nel tuo account o in un'organizzazione di tua proprietà.

Autorizza l'installazione utilizzando il tuo account GitHub e seleziona le autorizzazioni del repository quando richiesto.
Verifica l'installazione della tua connessione GitHub eseguendo questo comando:
```
 gcloud builds connections describe CONNECTION_NAME --region=REGION
```
Dove:
- CONNECTION_NAME è il nome della tua connessione.
- REGION è la regione per il trigger.
Se il campo installationState è impostato su COMPLETE, la connessione è stata installata. In caso contrario, il campo installationState fornisce un link per i passaggi aggiuntivi obbligatori.

Hai creato una connessione GitHub.

Connessione di un host GitHub in modo programmatico

Terraform

Puoi connettere l'host GitHub a Cloud Build utilizzando il provider Google Terraform, completando i seguenti passaggi:

Installa l'app GitHub di Cloud Build sul tuo account GitHub o in un'organizzazione di tua proprietà.
Crea un token di accesso personale.

Assicurati di impostare il token in modo che non abbia data di scadenza e seleziona le seguenti autorizzazioni quando richiesto in GitHub: repo e read:user. Se l'app è installata in un'organizzazione, assicurati di selezionare anche l'autorizzazione read:org.

Dopo aver generato il token di accesso personale, salva quello generato in un luogo sicuro. Utilizzerai il token generato nei passaggi seguenti.

Nota: se hai un token di autenticazione archiviato in un secret di una connessione creata in precedenza, puoi utilizzare lo stesso secret per la nuova connessione.

Nell'esempio seguente, lo snippet di codice esegue quanto segue:

Configura il provider Google Terraform
Crea un secret per archiviare i token di accesso personale GitHub per concedere all'agente di servizio Cloud Build le autorizzazioni di accesso al secret

Crea una connessione GitHub

// Configure the terraform google provider
terraform {
  required_providers {
    google = {}
   }
}

// Create a secret containing the personal access token and grant permissions to the Service Agent
resource "google_secret_manager_secret" "github_token_secret" {
    project =  PROJECT_ID
    secret_id = SECRET_ID

    replication {
        automatic = true
    }
}

resource "google_secret_manager_secret_version" "github_token_secret_version" {
    secret = google_secret_manager_secret.github_token_secret.id
    secret_data = GITHUB_PAT
}

data "google_iam_policy" "serviceagent_secretAccessor" {
    binding {
        role = "roles/secretmanager.secretAccessor"
        members = ["serviceAccount:service-PROJECT_NUMBER@gcp-sa-cloudbuild.iam.gserviceaccount.com"]
    }
}

resource "google_secret_manager_secret_iam_policy" "policy" {
  project = google_secret_manager_secret.github_token_secret.project
  secret_id = google_secret_manager_secret.github_token_secret.secret_id
  policy_data = data.google_iam_policy.serviceagent_secretAccessor.policy_data
}

// Create the GitHub connection
resource "google_cloudbuildv2_connection" "my_connection" {
    project = PROJECT_ID
    location = REGION
    name = CONNECTION_NAME

    github_config {
        app_installation_id = INSTALLATION_ID
        authorizer_credential {
            oauth_token_secret_version = google_secret_manager_secret_version.github_token_secret_version.id
        }
    }
    depends_on = [google_secret_manager_secret_iam_policy.policy]
}

Dove:

PROJECT_NUMBER è il numero del tuo progetto Google Cloud.
SECRET_ID è l'ID del token o del secret in Secret Manager.
GITHUB_PAT è l'ID del tuo token di accesso personale in GitHub.
PROJECT_ID è l'ID del tuo progetto Google Cloud.
REGION è la regione per la tua connessione.
CONNECTION_NAME è il nome della tua connessione GitHub.
INSTALLATION_ID è l'ID di installazione della tua app GitHub di Cloud Build. Puoi trovare l'ID di installazione nell'URL dell'app GitHub di Cloud Build. Nel seguente URL, https://github.com/settings/installations/1234567, l'ID di installazione è il valore numerico 1234567.

Hai creato una connessione GitHub.

gcloud

Per connettere l'host GitHub utilizzando un token e un ID di installazione esistenti ottenuti da una connessione precedente, completa i seguenti passaggi:

Installa l'app GitHub di Cloud Build sul tuo account GitHub o in un'organizzazione di tua proprietà.
Crea un token di accesso personale.

Assicurati di impostare il token in modo che non abbia data di scadenza e seleziona le seguenti autorizzazioni quando richiesto in GitHub: repo e read:user. Se l'app è installata in un'organizzazione, assicurati di selezionare anche l'autorizzazione read:org.

Dopo aver generato il token di accesso personale, salva quello generato in un luogo sicuro. Utilizzerai il token generato nei passaggi seguenti.

Nota: se hai un token di autenticazione archiviato in un secret di una connessione creata in precedenza, puoi utilizzare lo stesso secret per la nuova connessione.
Archivia il token in Secret Manager nel tuo progetto Google Cloud eseguendo questo comando:
```
    echo -n TOKEN | gcloud secrets create SECRET_NAME --data-file=-
```
Dove:
- TOKEN è il tuo token di accesso personale.
- SECRET_NAME è il nome che vuoi assegnare al tuo secret in Secret Manager.

Concedi l'accesso all'agente di servizio Cloud Build sul secret, dove SECRET_NAME è il nome del secret archiviato in Secret Manager:

  PROJECT_ID=$(gcloud config list --format="value(core.project)")
  PN=$(gcloud projects describe ${PROJECT_ID} --format="value(projectNumber)")
  CLOUD_BUILD_SERVICE_AGENT="service-${PN}@gcp-sa-cloudbuild.iam.gserviceaccount.com"
  gcloud secrets add-iam-policy-binding SECRET_NAME \
    --member="serviceAccount:${CLOUD_BUILD_SERVICE_AGENT}" \
    --role="roles/secretmanager.secretAccessor"

Crea la tua connessione GitHub:
```
  gcloud builds connections create github CONNECTION_NAME \
    --authorizer-token-secret-version=projects/PROJECT_ID/secrets/SECRET_NAME/versions/1  \
    --app-installation-id=INSTALLATION_ID --region=REGION
```
Dove:
- CONNECTION_NAME è il nome della tua connessione.
- PROJECT_ID è l'ID del tuo progetto Google Cloud.
- SECRET_NAME è il nome del secret archiviato in Secret Manager.
- INSTALLATION_ID è l'ID di installazione della tua app GitHub. Puoi trovare l'ID di installazione nell'URL dell'app GitHub di Cloud Build. Nel seguente URL, https://github.com/settings/installations/1234567, l'ID di installazione è il valore numerico 1234567.
- REGION è la regione della tua connessione.

Hai creato una connessione GitHub.

Connessione di un repository GitHub

Console

Per connettere un repository GitHub a una connessione host, completa i seguenti passaggi:

Apri la pagina Repositories nella console Google Cloud.

Apri la pagina Repository

Verrà visualizzata la pagina Repositories.
Nella parte superiore della pagina, seleziona la scheda 2a generazione.
Fai clic su Collega repository per collegare i repository dalla tua connessione.

Verrà visualizzato il riquadro Connetti repository.
Nel riquadro Connetti repository, inserisci le seguenti informazioni:
1. Connessione: seleziona una connessione dal menu a discesa.
2. Repository: seleziona un repository da collegare alla connessione.
3. Nome repository: inserisci un nome per il repository.
  1. Generato: seleziona questa opzione per fare in modo che Cloud Build generi automaticamente i nomi dei repository per tuo conto per i repository selezionati.
  2. Manuale: seleziona questa opzione per specificare manualmente i nomi dei repository selezionati.
    
    Se selezioni Manuale, puoi modificare i nomi dei repository selezionati nella sezione Nomi repository.
Fai clic su Collega per collegare il repository alla tua connessione.

Hai collegato correttamente il repository GitHub alla tua connessione.

gcloud

Per aggiungere un repository GitHub alla tua connessione, inserisci il seguente comando:

   gcloud builds repositories create REPO_NAME \
     --remote-uri=REPO_URI \
     --connection=CONNECTION_NAME --region=REGION

Dove:

REPO_NAME è il nome del repository.
REPO_URI è il link al tuo repository GitHub. Ad esempio, https://github.com/cloud-build/test-repo.git.
CONNECTION_NAME è il nome della tua connessione.
REGION è la regione per la tua connessione.

Hai collegato un repository alla tua connessione GitHub.

Terraform

Per aggiungere un repository GitHub alla tua connessione, aggiungi il seguente snippet di codice alla configurazione Terraform:

    resource "google_cloudbuildv2_repository" "my_repository" {
      project = "PROJECT_ID"
      location = "REGION"
      name = "REPO_NAME"
      parent_connection = google_cloudbuildv2_connection.my_connection.name
      remote_uri = "URI"
  }

Dove:

PROJECT_ID è l'ID del tuo progetto Google Cloud.
REPO_NAME è il nome del tuo repository GitHub.
REGION è la regione per la tua connessione.
URI è l'URI host del repository. Ad esempio, https://github.com/myuser/myrepo.git.

Hai collegato un repository alla tua connessione GitHub.

Passaggi successivi

Scopri come creare repository da GitHub.
Scopri come eseguire deployment blu/verde su Compute Engine.