Connettiti a un host GitHub Enterprise

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

Prima di iniziare

Abilita le API Cloud Build and Secret Manager.
Abilita le API

Assicurati di disporre dell'ultima versione di GitHub Enterprise.
Assicurati di mappare un dominio personalizzato al tuo host GitHub Enterprise e di disporre di un certificato SSL valido per l'host.

Nota: se il tuo host GitHub Enterprise è in esecuzione su un'istanza Compute Engine, puoi creare un bilanciatore del carico HTTP(s) esterno e utilizzare un certificato SSL gestito da Google per la tua istanza.
Se la tua istanza GitHub Enterprise è ospitata su una rete privata, consulta Creare repository da GitHub Enterprise in una rete privata prima di completare le istruzioni in questa pagina.

Autorizzazioni IAM richieste

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

Per aggiungere i ruoli richiesti al tuo account utente, vedi Configurare l'accesso alle risorse di 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 di Secret Manager (roles/secretmanager.admin) all'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 su una rete privata, consulta Creare repository da GitHub Enterprise in una rete privata per saperne di più sui ruoli IAM aggiuntivi richiesti prima della connessione host.

Connessione a un host GitHub Enterprise

Console

Per connettere il tuo host GitHub Enterprise a Cloud Build:

Apri la pagina Repositories nella console Google Cloud.

Apri la pagina Repository

Verrà visualizzata la pagina Repositories.
Nel selettore dei progetti nella barra superiore, seleziona il tuo progetto Google Cloud.
Nella parte superiore della pagina, seleziona la scheda 2a generazione.
Fai clic su Crea connessione host per connettere un nuovo host a Cloud Build.
Nel riquadro a sinistra, seleziona GitHub Enterprise come provider di origine.
Nella sezione Configura connessione, inserisci le informazioni seguenti:
1. Regione: seleziona una regione per la connessione.
  
  Nota: devi specificare una regione. La connessione non può esistere a livello globale.
2. Nome: inserisci un nome per la connessione,
Nella sezione Dettagli host, inserisci le seguenti informazioni:
1. Host URL (URL host): inserisci l'URL dell'host per la connessione. Ad esempio, github.example.com
2. Certificato CA: fai clic su Sfoglia per caricare il certificato autofirmato.
  
  Nota: il certificato non deve superare i 10 kB e deve essere in formato PEM (.pem, .cer o .crt). Se questa sezione viene lasciata vuota, verrà utilizzato un set predefinito di certificati.
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 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 preseleziona l'area geografica della connessione. L'area geografica 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.
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 utente o un'organizzazione. 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 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 dell'agente di servizio Cloud Build (service-{projectNumber}@gcp-sa-cloudbuild.iam.gserviceaccount.com) viene utilizzato per accedere al secret. Per visualizzare il secret, consulta Elencare i secret e visualizzare i dettagli del secret.

Dopo aver autorizzato l'app GitHub di Cloud Build, verrà visualizzata la pagina Repositories di Cloud Build.

Hai creato correttamente una connessione GitHub Enterprise.

gcloud

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

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 tua 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 la tua 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 servizio.
- SERVICE_NAME è il nome del servizio nello spazio dei nomi.
- SSL_CA_FILEPATH è il percorso file del certificato CA.
Dopo aver eseguito il comando gcloud builds connections..., riceverai un link per installare l'app GitHub di Cloud Build.
Segui il link restituito nel passaggio precedente per creare e installare l'app GitHub di Cloud Build sul tuo server aziendale.
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, la connessione è stata installata. In caso contrario, il campo installationState fornisce un link per i passaggi aggiuntivi obbligatori.

Hai creato correttamente una connessione 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:

Registra una nuova app GitHub. Ad esempio, puoi registrare una nuova app GitHub all'indirizzo https://my-ghe-server.net/settings/apps/new.
Completa i campi della pagina:
1. Nome app GitHub: inserisci un nome per l'app.
2. Home page URL (URL home page): inserisci un URL per il 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 del 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 connessione.
  - Segreto webhook: inserisci una stringa generata in modo casuale e prendi nota della stringa.
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 di commit: sola lettura
    - Richieste di pull: sola lettura
6. Nella sezione Iscriviti agli eventi, seleziona le seguenti caselle:
  - Controlla la corsa
  - Controlla suite
  - Esegui il commit del commento
  - Commento del problema
  - Richiesta di pull
  - Commento di revisione della richiesta di pull
  - Spingi
  - Repository
7. Seleziona la casella Qualsiasi account per consentire a qualsiasi utente o organizzazione di installare la tua app GitHub.
Fai clic su Crea app GitHub per creare la tua app GitHub.

Dopo aver fatto clic su Crea app GitHub, si aprirà la pagina dell'app. Prendi nota del tuo ID e dello slug dell'app. Puoi trovare lo slug dell'app nell'ultimo segmento dell'URL della pagina. Ad esempio, https://my-ghe-server.net/settings/apps/{app-slug}
Nella sezione Chiavi private, fai clic su Genera una chiave privata.

Archivia il file scaricato in un luogo sicuro.
Nel riquadro a sinistra, seleziona Installa app.

Seleziona l'utente o l'organizzazione in cui vuoi installare l'app. Dopo aver installato l'app, prendi nota dell'ID di installazione. L'ID di installazione è disponibile 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 passaggi seguenti 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.

Nell'esempio seguente, lo snippet di codice esegue quanto segue:

Configura il provider Google Terraform
Crea un secret per archiviare la chiave privata e il secret del 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 {
        automatic = true
    }
}

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 {
        automatic = true
    }
}

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 che contiene la chiave privata dell'app GitHub.
WEBHOOK_SECRET è il nome del secret contenente 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 è 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. Puoi trovare l'ID di installazione nell'URL della tua app GitHub di Cloud Build, https://github.com/settings/installations/{installation-id}.

Hai creato correttamente una connessione GitHub Enterprise.

gcloud

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

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 secret del webhook.
PRIVATE_KEY_FILE è il percorso file della chiave privata generata.

Concedi l'accesso all'agente di servizio Cloud Build per accedere ai 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 per progetto.

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 tua 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 di 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 tua 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 servizio.
- SERVICE_NAME è il nome del servizio nello spazio dei nomi.
- SSL_CA_FILEPATH è il percorso file del certificato CA.

Hai creato correttamente una connessione GitHub Enterprise.

Passaggi successivi

Scopri come connettere un repository a GitHub Enterprise.
Scopri come eseguire deployment blu/verde su Compute Engine.