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, concedi il ruolo Amministratore delle connessioni Cloud Build (roles/cloudbuild.connectionAdmin) al tuo account utente.

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

Per creare connessioni utilizzando gcloud passaggi di installazione, concedi la Ruolo Amministratore Secret Manager (roles/secretmanager.admin) per l'agente di servizio Cloud Build eseguendo questo 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 il tuo host GitHub Enterprise a Cloud Build:

  1. Apri la pagina Repositori nella console Google Cloud.

    Apri la pagina Repositori

    Verrà 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 Enterprise come fornitore 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 Host details (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 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 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 App GitHub 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. Cloud Build Account dell'agente di servizio (service-{projectNumber}@gcp-sa-cloudbuild.iam.gserviceaccount.com) viene utilizzato per accedere al secret. Per visualizzare il tuo secret, consulta Elenca i secret e visualizza i dettagli dei secret.

    Dopo aver autorizzato l'app GitHub di Cloud Build, reindirizzato ai repository di Cloud Build .

Hai creato una connessione 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 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 per la tua connessione.

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

    Se il campo installationState è impostato su COMPLETE, hai completato ha installato 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 in modo programmatico a Cloud Build: 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. Completa 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 Fai scadere i token di autorizzazione dell'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.
      • Segreto webhook. Inserisci una stringa generata in modo casuale e annotala.
    5. Nella sezione Autorizzazioni, specifica le seguenti autorizzazioni:
      • Autorizzazioni dei repository:
        • Controlli: lettura e scrittura
        • Contenuti: lettura e scrittura
        • Problemi: sola lettura
        • Metadati di sola lettura
        • Stati di commit: sola lettura
        • Richieste pull: sola lettura
    6. Nella sezione Iscriviti agli eventi, seleziona le seguenti caselle:
      • Controlla corsa
      • Verifica suite
      • Esegui il commit del commento
      • Commento sul problema
      • Richiesta di pull
      • Commento della revisione della richiesta di pull
      • Push
      • Repository
    7. Seleziona la casella Qualsiasi account per consentire a qualsiasi utente o organizzazione di installare l'app GitHub.

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

    Dopo aver fatto clic su Crea app GitHub, si aprirà la 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.

    Archivia 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 connetti il tuo host GitHub Enterprise in modo programmatico utilizzando Terraform gcloud.

Terraform

Dopo aver installato l'app GitHub, puoi connettere il tuo host GitHub Enterprise in Cloud Build con il provider Google Terraform.

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 le autorizzazioni necessarie all'agente di servizio Cloud Build 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 del tuo 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 dell'app GitHub.
  • REGION è la regione per la tua connessione.
  • CONNECTION_NAME è il nome della tua 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 di installazione della tua app GitHub. Il tuo disponibile nell'URL di Cloud Build App GitHub, 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 connetti il tuo host GitHub Enterprise in modo programmatico 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 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 del tuo progetto Google Cloud.
    • CLOUD_BUILD_SERVICE_AGENT è il tuo account per prodotto e progetto.

  3. Crea la tua 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 è 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 del tuo 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 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 tuo 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 del tuo progetto Google Cloud.
    • REGION è la regione per la tua connessione.
    • NAMESPACE è lo spazio dei nomi del tuo 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