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 e Secret Manager.

    Ruoli richiesti per abilitare le API

    Per abilitare le API, devi disporre del ruolo IAM Amministratore utilizzo dei servizi (roles/serviceusage.serviceUsageAdmin), che include l'autorizzazione serviceusage.services.enable. Scopri come concedere i ruoli.

    Abilita le API

  • Prepara il codice sorgente in un repository GitHub.
  • Avere un Dockerfile o un file di configurazione Cloud Build nel repository di origine GitHub.
  • Se stai connettendo inizialmente il repository a Cloud Build, assicurati di disporre delle autorizzazioni a livello di amministratore per il repository. Per saperne di più sulle autorizzazioni del repository GitHub, consulta Livelli di autorizzazione del repository per un'organizzazione.

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

Connettiti a un host GitHub

Console

Per connettere il tuo repository GitHub a Cloud Build:

  1. Apri la pagina Repository nella console Google Cloud .

    Apri la pagina Repository

    Viene visualizzata la pagina Repository.

  2. Nel selettore di progetti nella barra superiore, seleziona il tuo progetto Google Cloud .

  3. Nella parte superiore della pagina, seleziona la scheda 2ª gen..

  4. Fai clic su Crea connessione host per connettere un nuovo host a Cloud Build.

  5. Nel riquadro a sinistra, seleziona GitHub come provider di origine.

  6. Nella sezione Configura connessione, inserisci le seguenti informazioni:

    • Regione: seleziona una regione per la connessione.

    • Name (Nome): inserisci un nome per la connessione.

  7. (Facoltativo) Se vuoi gestire le chiavi di crittografia utilizzate per criptare i token di accesso per i tuoi repository GitHub, vai alla sezione Crittografia e scegli una chiave Cloud Key Management Service. Per saperne di più, vedi Attivare le chiavi di crittografia gestite dal cliente per Secret Manager.

  8. Fai clic su Connetti.

    Dopo aver fatto clic sul pulsante Connetti, ti viene chiesto di autorizzare l'app GitHub di Cloud Build ad accedere al tuo account GitHub. Puoi revocare l'accesso all'app disinstallandola o eliminandola 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 del tuo account utente per l'installazione dell'app GitHub di Cloud Build e ai repository collegati. Il service agent Cloud Build (service-{projectNumber}@gcp-sa-cloudbuild.iam.gserviceaccount.com) viene utilizzato per accedere al tuo secret. Per visualizzare il secret, consulta Elencare i secret e visualizzarne i dettagli.

    Dopo aver autorizzato l'app GitHub di Cloud Build, viene eseguito il reindirizzamento alla pagina Repository di Cloud Build.

gcloud

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

  1. Inserisci il comando seguente per avviare una connessione al tuo repository GitHub:

     gcloud builds connections create github CONNECTION_NAME --region=REGION

    Dove:

    • CONNECTION_NAME è un nome per la connessione così come verrà visualizzato in Cloud Build.

    • REGION è la regione del trigger.

    Dopo aver eseguito il comando gcloud builds connections, viene visualizzato un link per autorizzare l'app GitHub di Cloud Build.

  2. Accedi al tuo account github.com.

  3. 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.

  4. Installa l'app GitHub di Cloud Build nel tuo account o in un'organizzazione di tua proprietà.

    Consenti l'installazione utilizzando il tuo account GitHub e seleziona le autorizzazioni del repository quando ti viene richiesto.

  5. Verifica l'installazione della connessione GitHub eseguendo il seguente comando:

     gcloud builds connections describe CONNECTION_NAME --region=REGION

    Dove:

    • CONNECTION_NAME è il nome della connessione host GitHub in Cloud Build.
    • REGION è la regione del trigger.

    Se il campo installationState è impostato su COMPLETE, l'installazione della connessione è stata eseguita correttamente. In caso contrario, il campo installationState fornisce un link per i passaggi aggiuntivi richiesti.

Connettiti a un host GitHub in modo programmatico

Per connetterti a un host GitHub in modo programmatico, devi prima configurare il token di autenticazione per la connessione, quindi creare la connessione GitHub in Cloud Build.

Configura un token di autenticazione

Per connetterti a un host GitHub in modo programmatico, devi creare una connessione GitHub Cloud Build, incluso un secret per un token di autenticazione. Puoi acquisire un token di autenticazione in due modi:

  • Crea un token di accesso personale in GitHub.

  • Utilizza un token da una connessione Cloud Build GitHub esistente. Questo metodo è utile se il tuo account GitHub presenta limitazioni che impediscono la creazione di token di accesso personale. Inoltre, se fai riferimento a questo token quando crei una connessione da uno script, non devi autenticare manualmente la connessione utilizzando un browser web.

Token di accesso personale

  1. Segui i passaggi per creare un token di accesso personale nella documentazione di GitHub.

  2. Seleziona i seguenti ambiti OAuth quando richiesto in GitHub:

    • repo per concedere l'accesso completo ai repository pubblici e privati.
    • read:user per concedere l'accesso alla lettura dei dati del profilo di un utente.
    • read:org per l'accesso di sola lettura all'appartenenza all'organizzazione e ai progetti (se l'app è installata in un'organizzazione).

  3. Salva il valore del token di accesso personale. Lo utilizzerai in un passaggio successivo.

Connessione esistente

  1. Esegui questo comando in gcloud CLI:

    gcloud builds connections describe CONNECTION_NAME --region=REGION

    Dove:

    • CONNECTION_NAME è il nome della connessione all'host GitHub.
    • REGION è la regione del trigger.

  2. Nell'output comando, il valore di authorizerTokenSecretVersion è l'ID del secret contenente il token di autenticazione della connessione. Copia questo valore e salvalo in un luogo sicuro. Utilizzerai il token generato nei passaggi successivi.

Crea la connessione GitHub

Crea una connessione GitHub utilizzando Terraform o gcloud CLI.

Terraform

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

  1. Installa l'app GitHub di Cloud Build nel tuo account GitHub o in un'organizzazione di tua proprietà.

  2. Configura la connessione GitHub in Terraform. Il seguente esempio di codice Terraform mostra una configurazione che esegue le seguenti operazioni:

    • Configura il provider Google Terraform

    • Crea un secret per archiviare i token di accesso personale di GitHub

    • Concede le autorizzazioni all'agente di servizio Cloud Build per accedere 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 {
        auto {}
    }
}

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 tuo token di accesso personale o segreto GitHub in Secret Manager.
  • GITHUB_PAT è il token di accesso del token di accesso personale in GitHub.
  • PROJECT_ID è l'ID progetto Google Cloud .
  • REGION è la regione per la connessione.
  • CONNECTION_NAME è un nome per la connessione così come verrà visualizzato in Cloud Build.
  • INSTALLATION_ID è l'ID installazione dell'app GitHub di Cloud Build. Puoi trovare l'ID installazione nell'URL dell'app GitHub di Cloud Build. Nell'URL seguente, https://github.com/settings/installations/1234567, l'ID installazione è il valore numerico 1234567.

gcloud

Per connettere l'host GitHub a Cloud Build:

  1. Installa l'app GitHub di Cloud Build nel tuo account GitHub o in un'organizzazione di tua proprietà.

  2. Facoltativo. Se utilizzi un token di accesso personale GitHub per l'autenticazione, esegui questo comando per archiviare il token in Secret Manager nel tuo progetto Google Cloud :

    echo -n 'TOKEN' | gcloud secrets create SECRET_NAME --data-file=-

  3. Concedi l'accesso al service agent Cloud Build al 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"

  4. Crea la connessione GitHub:

    gcloud builds connections create github CONNECTION_NAME \
  --authorizer-token-secret-version=projects/PROJECT_ID/secrets/SECRET_NAME/versions/VERSION  \
  --app-installation-id=INSTALLATION_ID --region=REGION

    Dove:

    • CONNECTION_NAME è il nome della connessione host GitHub in Cloud Build.
    • PROJECT_ID è l'ID progetto Google Cloud .
    • SECRET_NAME è il nome del secret archiviato in Secret Manager.
    • VERSION è la versione del secret.
    • INSTALLATION_ID è l'ID installazione della tua app GitHub. Puoi trovare l'ID installazione nell'URL dell'app GitHub di Cloud Build. Nell'URL seguente, https://github.com/settings/installations/1234567, l'ID installazione è il valore numerico 1234567.
    • REGION è la regione della connessione.

Connetti un repository GitHub

Console

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

  1. Apri la pagina Repository nella console Google Cloud .

    Apri la pagina Repository

    Viene visualizzata la pagina Repository.

  2. Nella parte superiore della pagina, seleziona la scheda 2ª gen..

  3. Fai clic su Collega repository per collegare i repository dalla connessione.

    Viene visualizzato il riquadro Connetti repository.

  4. 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. Generati: seleziona questa opzione per consentire a Cloud Build di generare 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.

  5. Fai clic su Collega per collegare il repository alla connessione.

gcloud

Per aggiungere un repository GitHub alla 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 assegnato alla connessione host GitHub Enterprise creata in Cloud Build da Connetti a un host GitHub.
  • REGION è la regione per la connessione.

Terraform

Per aggiungere un repository GitHub alla 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 progetto Google Cloud .
  • REPO_NAME è il nome del tuo repository GitHub.
  • REGION è la regione per la connessione.
  • URI è l'URI host del tuo repository. Ad esempio, https://github.com/myuser/myrepo.git.

Passaggi successivi