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

  • Enable the Cloud Build and Secret Manager APIs.

    Enable the APIs

  • Prepara il codice sorgente in un repository GitHub.
  • Avere un Dockerfile o un file di configurazione Cloud Build nel repository di origine GitHub.
  • Se inizialmente connetti 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.

Autorizzazioni IAM richieste

Per connettere l'host GitHub, concedi il ruolo Amministratore connessioni Cloud Build (roles/cloudbuild.connectionAdmin) al tuo account utente.

Per aggiungere i ruoli richiesti al tuo account utente, consulta Configurazione dell'accesso alle risorse Cloud Build. Per scoprire di più sui ruoli IAM associati a Cloud Build, consulta Ruoli e autorizzazioni IAM.

Per creare connessioni utilizzando i passaggi di installazione di gcloud, concedi il ruolo Amministratore Secret Manager (roles/secretmanager.admin) all'agente di servizio Cloud Build eseguendo il seguente comando nel tuo progettoGoogle Cloud :

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

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 Google Cloud progetto.

  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:

    1. Regione: seleziona una regione per la connessione.

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

  7. 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 Cloud Build GitHub e ai repository collegati. L'account Cloud Build Service Agent (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 seguente comando per avviare una connessione al repository GitHub:

     gcloud builds connections create github CONNECTION_NAME --region=REGION

    Dove:

    • CONNECTION_NAME è un nome per la connessione così come verrà visualizzata 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 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, la connessione è stata installata correttamente. In caso contrario, il campo installationState fornisce un link per i passaggi aggiuntivi richiesti.

Connettersi a un host GitHub in modo programmatico

Terraform

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

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

  2. Crea un token di accesso personale.

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

    Dopo aver generato il token di accesso personale, salvalo in un luogo sicuro. Utilizzerai il token generato nei passaggi successivi.

Nel seguente esempio, lo snippet di codice esegue queste operazioni:

  • Configura il provider Google Terraform

  • Crea un secret per archiviare i token di accesso personale GitHub per concedere 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 token o del secret in Secret Manager.
  • GITHUB_PAT è l'ID del tuo token di accesso personale in GitHub.
  • PROJECT_ID è l'ID progetto Google Cloud .
  • REGION è la regione per la tua connessione.
  • CONNECTION_NAME è un nome per la connessione così come verrà visualizzata 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 utilizzando un token e un ID installazione esistenti ottenuti da una connessione precedente, completa i seguenti passaggi:

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

  2. Crea un token di accesso personale.

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

    Dopo aver generato il token di accesso personale, salvalo in un luogo sicuro. Utilizzerai il token generato nei passaggi successivi.

  3. Archivia il token in Secret Manager nel tuo Google Cloud progetto 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.

  4. Concedi l'accesso all'agente di servizio 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"

  5. Crea la 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 connessione host GitHub in Cloud Build.
    • PROJECT_ID è l'ID progetto Google Cloud .
    • SECRET_NAME è il nome del secret archiviato in Secret Manager.
    • 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 tua connessione.

Connetti un repository GitHub

Console

Per connettere un repository GitHub a una connessione all'host:

  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 tuo 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 tua 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 tua connessione.
  • URI è l'URI host del tuo repository. Ad esempio, https://github.com/myuser/myrepo.git.

Passaggi successivi