Connettiti a un host GitHub Enterprise

Questa pagina spiega come connettere 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, assegna il ruolo Amministratore connessione 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 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 host.

Connettiti 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 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 Enterprise 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. 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. Internet pubblico: seleziona questa opzione se la tua istanza è accessibile tramite internet pubblico.

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

      3. Nella sezione Servizio Service 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 pre-seleziona la regione della connessione. La regione specificata per il tuo servizio deve corrispondere alla regione associata alla tua connessione.

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

        3. Servizio: seleziona il nome del servizio nel tuo 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 dell'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 tua chiave privata e il secret del 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 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, verrà eseguito il reindirizzamento alla pagina Repository di Cloud Build.

gcloud

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

  1. Inserisci questo comando per creare una connessione GitHub Enterprise:

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

    Dove:

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

    Se la tua istanza GitHub Enterprise si trova in una rete privata, specifica la risorsa Service Directory. Puoi anche specificare il certificato 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 per la tua connessione.
    • NAMESPACE è lo spazio dei nomi per il tuo servizio.
    • SERVICE_NAME è il nome del tuo servizio nello spazio dei nomi.
    • SSL_CA_FILEPATH è il percorso 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 Cloud Build GitHub sul 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 host GitHub Enterprise in Cloud Build.
    • REGION è la regione per la tua connessione.

    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.

Connettiti a un host GitHub Enterprise in modo programmatico

Per connettere il tuo host GitHub Enterprise a Cloud Build in modo programmatico, devi installare l'app GitHub completando i seguenti passaggi:

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

  2. Compila i campi della pagina:

    1. Nome app GitHub: inserisci un nome per l'app.
    2. URL della home page: inserisci un URL per GitHub Enterprise Server.
    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 webhook.
      • URL webhook: inserisci l'URL webhook. Ad esempio, https://cloudbuild.googleapis.com/v2/projects/{PROJECT_NUMBER}/locations/{REGION}/connections:processWebhook. La regione nell'URL webhook deve corrispondere a quella della tua connessione.
      • Webhook secret: inserisci una stringa generata in modo casuale e annotala.
    5. Nella sezione Autorizzazioni, specifica le seguenti autorizzazioni:
      • Autorizzazioni repository:
        • Controlli: lettura e scrittura
        • Contenuti: lettura e scrittura
        • Problemi: sola lettura
        • Metadati Sola lettura
        • Stati dei commit: sola lettura
        • Richieste di pull: sola lettura
    6. Nella sezione Iscriviti agli eventi, seleziona le seguenti caselle:
      • Check run
      • Check suite
      • Commento del commit
      • Commento sul problema
      • Richiesta di pull
      • Commento di 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à eseguito il reindirizzamento alla pagina dell'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, prendi nota dell'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 connettere 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 Google Terraform.

Nel seguente esempio, lo snippet di codice esegue queste 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 dell'app GitHub.
  • WEBHOOK_SECRET è il nome del secret che contiene il valore del secret webhook dell'app GitHub.
  • WEBHOOK_SECRET_VALUE è il valore del secret del webhook dell'app GitHub.
  • REGION è la regione per la tua connessione.
  • CONNECTION_NAME è un nome per la connessione host GitHub Enterprise in Cloud Build.
  • URI è l'URI della tua 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}.

gcloud

Dopo aver installato l'app GitHub, completa i seguenti passaggi per connettere il tuo host GitHub Enterprise in modo programmatico utilizzando gcloud:

  1. Archivia i 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 secret webhook.
    • PRIVATE_KEY_FILE è il percorso 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 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 è un nome per la connessione host GitHub Enterprise in Cloud Build.
    • 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 dell'app GitHub. Ad esempio, https://my-ghe-server.net/settings/installations/installation-id
    • REGION è la regione per la tua connessione.

    Se la tua istanza GitHub Enterprise si trova in una rete privata, specifica la risorsa Service Directory. Puoi anche specificare il certificato 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 per la tua connessione.
    • NAMESPACE è lo spazio dei nomi del tuo servizio.
    • SERVICE_NAME è il nome del tuo servizio nello spazio dei nomi.
    • SSL_CA_FILEPATH è il percorso del certificato CA.

Passaggi successivi