Connettiti a un host GitHub Enterprise

Questa pagina spiega come collegare un host GitHub Enterprise a Cloud Build.

Prima di iniziare

  • Enable the Cloud Build and Secret Manager APIs.

    Enable the APIs

Autorizzazioni IAM richieste

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

Per aggiungere i ruoli richiesti al tuo account utente, consulta Configurare l'accesso alle risorse Cloud Build. Per approfondire i ruoli IAM associati a Cloud Build, consulta Ruoli e autorizzazioni IAM.

Per creare connessioni utilizzando i passaggi di installazione di gcloud, concedi il ruolo di amministratore di Secret Manager (roles/secretmanager.admin) all'agente di servizio Cloud Build eseguendo il seguente comando nel tuo progetto Google 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"

Se la tua istanza GitHub Enterprise è ospitata in una rete privata, consulta Creare repository da GitHub Enterprise in una rete privata per scoprire i ruoli IAM aggiuntivi richiesti prima della connessione all'host.

Connessione a un host GitHub Enterprise

Console

Per connettere l'host GitHub Enterprise a Cloud Build:

  1. Apri la pagina Repository nella console Google Cloud .

    Apri la pagina Repositori

    Viene visualizzata la pagina Repositori.

  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 collegare un nuovo host a Cloud Build.

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

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

    1. Regione: seleziona una regione per la connessione.

    2. Nome: inserisci un nome per la connessione.

  7. Nella sezione Dettagli host, inserisci le seguenti informazioni:

    1. URL host: inserisci l'URL host per la connessione. Ad esempio, github.example.com

    2. Certificato CA: fai clic su Sfoglia per caricare il certificato autofirmato.

    3. In Tipo di connessione, seleziona una delle seguenti opzioni:

      1. Rete internet pubblica: seleziona questa opzione se l'istanza è accessibile tramite la rete internet pubblica.

      2. Accesso alla rete privata: seleziona questa opzione se l'istanza è ospitata in una rete privata.

      3. In Servizio directory, seleziona la località del servizio:

        • Nel progetto your-project
        • In un altro progetto
        • Inserisci manualmente

        1. Se selezioni In un altro progetto o Inserisci manualmente, inserisci le seguenti informazioni:

          • Progetto: inserisci o seleziona l'ID progetto Google Cloud dal menu a discesa.

          • Regione: questo campo preseleziona la regione della connessione. La regione specificata per il servizio deve corrispondere a quella associata alla connessione.

        2. Spazio dei nomi: seleziona lo spazio dei nomi del servizio.

        3. Servizio: seleziona il nome del servizio nello spazio dei nomi.

  8. Fai clic su Connetti.

    Dopo aver fatto clic sul pulsante Connetti, ti verrà chiesto di creare un'app GitHub nel tuo host GitHub Enterprise e di installarla in un account o un'organizzazione utente. Un token di autenticazione del tuo host GitHub Enterprise verrà creato e archiviato in questo progetto come secret di Secret Manager. Puoi revocare l'accesso disinstallando o eliminando l'app GitHub dal tuo host in qualsiasi momento.

    Cloud Build archivia i dati di autenticazione dell'app GitHub creata come secret in Secret Manager nel tuo progetto. Questi dati includono la chiave privata e il secret webhook. La chiave privata viene utilizzata come metodo di autenticazione per accedere all'API di Enterprise Server. Il secret webhook viene utilizzato per convalidare gli eventi inviati dal server a Cloud Build. L'account agente di servizio Cloud Build (service-{projectNumber}@gcp-sa-cloudbuild.iam.gserviceaccount.com) viene utilizzato per accedere al tuo segreto. Per visualizzare il tuo secret, consulta Elenca i secret e visualizza i dettagli dei secret.

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

Hai creato una connessione a GitHub Enterprise.

gcloud

Per connettere l'host GitHub Enterprise a Cloud Build utilizzando i comandi gcloud, segui questi passaggi:

  1. Inserisci il comando seguente per creare una connessione a GitHub Enterprise:

    gcloud builds connections create github-enterprise CONNECTION_NAME \
  --host-uri=HOST_URI --region=REGION

    Dove:

    • CONNECTION_NAME è il nome della connessione.
    • HOST_URI è l'URI della tua istanza GitHub Enterprise. Ad esempio, https://mmy-ghe-server.net.
    • REGION è la regione della tua connessione.

    Se la tua istanza GitHub Enterprise si trova in una rete privata, specifica la risorsa Service Directory. Puoi anche specificare il certificato della CA.

    --service-directory-service=projects/PROJECT_ID/locations/REGION/namespaces/NAMESPACE/services/SERVICE_NAME \
--ssl-ca-file=SSL_CA_FILEPATH

    Dove:

    • PROJECT_ID è l'ID progetto Google Cloud .
    • REGION è la regione della tua connessione.
    • NAMESPACE è lo spazio dei nomi del servizio.
    • SERVICE_NAME è il nome del servizio nello spazio dei nomi.
    • SSL_CA_FILEPATH è il percorso del file del certificato CA.

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

  2. Segui il link restituito nel passaggio precedente per creare e installare l'app GitHub Cloud Build sul tuo server aziendale.

  3. Inserisci il seguente comando per verificare la connessione:

    gcloud builds connections describe CONNECTION_NAME --region=REGION

    Dove:

    • CONNECTION_NAME è il nome della connessione.
    • REGION è la regione della tua connessione.

    Se il campo installationState è impostato su COMPLETE, hai installato correttamente la connessione. In caso contrario, il campo installationState fornisce un link per i passaggi aggiuntivi richiesti.

Hai creato una connessione a GitHub Enterprise.

Connessione a un host GitHub Enterprise in modo programmatico

Per connettere l'host GitHub Enterprise a Cloud Build tramite programmazione, devi installare l'app GitHub completando i seguenti passaggi:

  1. Registra una nuova app GitHub. Ad esempio, puoi registrare una nuova app GitHub all'indirizzo https://my-ghe-server.net/settings/apps/new.

  2. Compila i campi nella pagina:

    1. Nome dell'app GitHub: inserisci un nome per l'app.
    2. URL home page: inserisci un URL per il tuo server GitHub Enterprise.
    3. Deseleziona la casella Scadenza dei token di autorizzazione utente.
    4. Nella sezione Webhook, completa i seguenti passaggi:
      • Attivo: seleziona la casella per attivare il webook.
      • URL webhook: inserisci l'URL webhook. Ad esempio, https://cloudbuild.googleapis.com/v2/projects/{PROJECT_NUMBER}/locations/{REGION}/connections:processWebhook. La regione nell'URL del webhook deve corrispondere alla regione della connessione.
      • Secret webhook: inserisci una stringa generata in modo casuale e prendine nota.
    5. Nella sezione Autorizzazioni, specifica le seguenti autorizzazioni:
      • Autorizzazioni del repository:
        • Controlli: lettura e scrittura
        • Contenuti: lettura e scrittura
        • Problemi: sola lettura
        • Metadati di sola lettura
        • Stati dei commit: di sola lettura
        • Richieste di pull: di sola lettura
    6. Nella sezione Iscriviti agli eventi, seleziona le seguenti caselle:
      • Eseguire il controllo
      • Suite di controllo
      • Commento del commit
      • Commento sul problema
      • Richiesta di pull
      • Commento della revisione della richiesta di pull
      • Push
      • Repository
    7. Seleziona la casella Qualsiasi account per consentire l'installazione dell'app GitHub da parte di qualsiasi utente o organizzazione.

  3. Fai clic su Crea app GitHub per creare l'app GitHub.

    Dopo aver fatto clic su Crea app GitHub, verrà visualizzata la pagina della tua app. Prendi nota dell'ID app e dello slug dell'app. Lo slug dell'app si trova nell'ultimo segmento dell'URL della pagina. Ad esempio, https://my-ghe-server.net/settings/apps/{app-slug}

  4. Nella sezione Chiavi private, fai clic su Genera una chiave privata.

    Conserva il file scaricato in un luogo sicuro.

  5. Nel riquadro a sinistra, seleziona Installa app.

    Seleziona l'utente o l'organizzazione in cui vuoi installare l'app. Dopo l'installazione dell'app, annota l'ID installazione. L'ID installazione si trova nell'ultimo segmento dell'URL della pagina. Ad esempio, https://my-ghe-server.net/settings/installations/{installation-id}.

Dopo aver installato l'app GitHub, completa i seguenti passaggi per collegare l'host GitHub Enterprise in modo programmatico utilizzando Terraform o gcloud.

Terraform

Dopo aver installato l'app GitHub, puoi connettere l'host GitHub Enterprise a Cloud Build utilizzando il provider Terraform di Google.

Nel seguente esempio, lo snippet di codice esegue le seguenti operazioni:

  • Configura il provider Google Terraform
  • Crea un secret per archiviare la chiave privata e il secret webhook dell'app GitHub
  • Concede all'agente di servizio Cloud Build le autorizzazioni necessarie per accedere ai secret

  • Crea una connessione GitHub Enterprise

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

// create Secrets and grant permissions to the Service Agent
resource "google_secret_manager_secret" "private-key-secret" {
    project = "PROJECT_ID"
    secret_id = "PRIVATE_KEY_SECRET"

    replication {
        auto {}
    }
}

resource "google_secret_manager_secret_version" "private-key-secret-version" {
    secret = google_secret_manager_secret.private-key-secret.id
    secret_data = file("private-key.pem")
}

resource "google_secret_manager_secret" "webhook-secret-secret" {
    project = "PROJECT_ID"
    secret_id = "WEBHOOK_SECRET"

    replication {
        auto {}
    }
}

resource "google_secret_manager_secret_version" "webhook-secret-secret-version" {
    secret = google_secret_manager_secret.webhook-secret-secret.id
    secret_data = "WEBHOOK_SECRET_VALUE"
}

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-pk" {
  project = google_secret_manager_secret.private-key-secret.project
  secret_id = google_secret_manager_secret.private-key-secret.secret_id
  policy_data = data.google_iam_policy.serviceagent-secretAccessor.policy_data
}

resource "google_secret_manager_secret_iam_policy" "policy-whs" {
  project = google_secret_manager_secret.webhook-secret-secret.project
  secret_id = google_secret_manager_secret.webhook-secret-secret.secret_id
  policy_data = data.google_iam_policy.serviceagent-secretAccessor.policy_data
}

// create the connection and add the repository resource ---
resource "google_cloudbuildv2_connection" "my-connection" {
    project = "PROJECT_ID"
    location = "REGION"
    name = "CONNECTION_NAME"

    github_enterprise_config {
        host_uri = "URI"
        private_key_secret_version = google_secret_manager_secret_version.private-key-secret-version.id
        webhook_secret_secret_version = google_secret_manager_secret_version.webhook-secret-secret-version.id
        app_id = "APP_ID"
        app_slug = "APP_SLUG"
        app_installation_id = INSTALLATION_ID
    }

    depends_on = [
        google_secret_manager_secret_iam_policy.policy-pk,
        google_secret_manager_secret_iam_policy.policy-whs
    ]
}

Dove:

  • PROJECT_ID è l'ID progetto Google Cloud .
  • PRIVATE_KEY_SECRET è il secret contenente la chiave privata della tua app GitHub.
  • WEBHOOK_SECRET è il nome del secret contenente il valore del secret webhook della tua app GitHub.
  • WEBHOOK_SECRET_VALUE è il valore del secret webhook della tua app GitHub.
  • REGION è la regione della tua connessione.
  • CONNECTION_NAME è il nome della connessione GitHub.
  • URI è l'URI della connessione. Ad esempio, https://my-github-enterprise-server.net.
  • APP_ID è l'ID della tua app GitHub.
  • APP_SLUG è lo slug dell'app. Ad esempio, https://github.com/settings/apps/{app-slug}.
  • INSTALLATION_ID è l'ID installazione della tua app GitHub. Puoi trovare l'ID installazione nell'URL dell'app GitHub di Cloud Build, https://github.com/settings/installations/{installation-id}.

Hai creato una connessione a GitHub Enterprise.

gcloud

Dopo aver installato l'app GitHub, completa i seguenti passaggi per collegare il tuo host GitHub Enterprise tramite programmazione utilizzando gcloud:

  1. Archivia i tuoi secret in Secret Manager:

    echo -n WEBHOOK_SECRET | gcloud secrets create mygheapp-webhook-secret --data-file=-
# creating secret from the downloaded private key:
gcloud secrets create mygheapp-private-key --data-file=PRIVATE_KEY_FILE

    Dove:

    • WEBHOOK_SECRET è la stringa che hai creato per il tuo secret webhook.
    • PRIVATE_KEY_FILE è il percorso del file della chiave privata che hai generato.

  2. Concedi all'agente di servizio Cloud Build l'accesso ai tuoi secret:

    PROJECT_NUMBER=$(gcloud projects describe PROJECT_ID --format="value(projectNumber)")
CLOUD_BUILD_SERVICE_AGENT="service-$PROJECT_NUMBER@gcp-sa-cloudbuild.iam.gserviceaccount.com"
gcloud secrets add-iam-policy-binding mygheapp-webhook-secret \
  --member="serviceAccount:CLOUD_BUILD_SERVICE_AGENT" \
  --role="roles/secretmanager.secretAccessor"
gcloud secrets add-iam-policy-binding mygheapp-private-key \
  --member="serviceAccount:CLOUD_BUILD_SERVICE_AGENT" \
  --role="roles/secretmanager.secretAccessor"

    Dove:

    • PROJECT_ID è l'ID progetto Google Cloud .
    • CLOUD_BUILD_SERVICE_AGENT è il tuo account Per prodotto per progetto.

  3. Crea la connessione a GitHub Enterprise:

    gcloud builds connections create github-enterprise CONNECTION_NAME \
  --host-uri=HOST_URI \
  --app-id=APP_ID \
  --app-slug=APP_SLUG \
  --private-key-secret-version=projects/PROJECT_ID/secrets/mygheapp-private-key/versions/1 \
  --webhook-secret-secret-version=projects/PROJECT_ID/secrets/mygheapp-webhook-secret/versions/1 \
  --app-installation-id=INSTALLATION_ID \
  --region=REGION

    Dove:

    • CONNECTION_NAME è il nome della connessione.
    • HOST_URI è l'URI della tua istanza GitHub Enterprise. Ad esempio, https://mmy-ghe-server.net.
    • APP_ID è l'ID della tua app GitHub.
    • APP_SLUG è lo slug dell'app. Ad esempio, https://my-ghe-server.net/settings/apps/app-slug.
    • PROJECT_ID è l'ID progetto Google Cloud .
    • INSTALLATION_ID è l'ID installazione della tua app GitHub. Ad esempio, https://my-ghe-server.net/settings/installations/installation-id
    • REGION è la regione della tua connessione.

    Se la tua istanza GitHub Enterprise si trova in una rete privata, specifica la risorsa Service Directory. Puoi anche specificare il certificato della CA.

      --service-directory-service=projects/PROJECT_ID/locations/REGION/namespaces/NAMESPACE/services/SERVICE_NAME \
  --ssl-ca-file=SSL_CA_FILEPATH

    Dove:

    • PROJECT_ID è l'ID progetto Google Cloud .
    • REGION è la regione della tua connessione.
    • NAMESPACE è lo spazio dei nomi del servizio.
    • SERVICE_NAME è il nome del servizio nello spazio dei nomi.
    • SSL_CA_FILEPATH è il percorso del file del certificato CA.

Hai creato una connessione a GitHub Enterprise.

Passaggi successivi