Verbindung zu einem GitHub Enterprise-Host herstellen

Auf dieser Seite wird erläutert, wie Sie einen GitHub Enterprise-Host mit Cloud Build verbinden.

Hinweise

  • Enable the Cloud Build and Secret Manager APIs.

    Enable the APIs

Erforderliche IAM-Berechtigungen

Zum Verbinden Ihres GitHub Enterprise-Hosts weisen Sie dem Nutzerkonto die Rolle „Cloud Build-Verbindungsadministrator“ (roles/cloudbuild.connectionAdmin) zu.

Informationen zum Hinzufügen der erforderlichen Rollen zu Ihrem Nutzerkonto finden Sie unter Zugriff auf Cloud Build-Ressourcen konfigurieren. Bis Weitere Informationen zu IAM-Rollen im Zusammenhang mit Cloud Build finden Sie unter IAM-Rollen und -Berechtigungen.

Wenn Sie Verbindungen mithilfe der Installationsschritte von gcloud erstellen möchten, gewähren Sie dem Cloud Build-Dienst-Agent die Rolle „Secret Manager-Administrator“ (roles/secretmanager.admin). Führen Sie dazu in Ihrem Google Cloud-Projekt den folgenden Befehl aus:

      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"

Wenn Ihre GitHub Enterprise-Instanz in einem privaten Netzwerk gehostet wird, finden Sie unter Repositories aus GitHub Enterprise in einem privaten Netzwerk erstellen Informationen zu zusätzlichen IAM-Rollen, die vor der Hostverbindung erforderlich sind.

Verbindung zu einem GitHub Enterprise-Host herstellen

Console

So verbinden Sie Ihren GitHub Enterprise-Host mit Cloud Build:

  1. Öffnen Sie in der Cloud Console die Seite Repositories.

    Zur Seite „Repositories“

    Die Seite Repositories wird angezeigt.

  2. Wählen Sie in der Projektauswahl in der oberen Leiste Ihr Google Cloud-Projekt aus.

  3. Wählen Sie oben auf der Seite den Tab 2. Generation aus.

  4. Klicken Sie auf Hostverbindung erstellen, um einen neuen Host mit Cloud Build zu verbinden.

  5. Wählen Sie im linken Bereich GitHub Enterprise als Quellanbieter aus.

  6. Geben Sie im Abschnitt Verbindung konfigurieren die folgenden Informationen ein:

    1. Region: Wählen Sie eine Region für die Verbindung aus.

    2. Name: Geben Sie einen Namen für die Verbindung ein.

  7. Geben Sie im Abschnitt Host Details (Hostdetails) die folgenden Informationen ein:

    1. Host-URL: Geben Sie die Host-URL für die Verbindung ein. z. B. github.example.com.

    2. CA-Zertifikat: Klicken Sie auf „Durchsuchen“, um Ihr selbst signiertes Zertifikat hochzuladen.

    3. Wählen Sie unter Verbindungstyp eine der folgenden Optionen aus:

      1. Öffentliches Internet: Wählen Sie diese Option aus, wenn auf Ihre Instanz über das öffentliche Internet zugegriffen werden kann.

      2. Privater Netzwerkzugriff: Wählen Sie diese Option aus, wenn die Instanz in einem privaten Netzwerk gehostet wird.

      3. Wählen Sie unter Service Directory-Dienst den Standort für Ihren Dienst aus:

        • Im Projekt your-project
        • In einem anderen Projekt
        • Manuell eingeben

        1. Wenn Sie In einem anderen Projekt oder Manuell eingeben auswählen, geben Sie folgende Informationen:

          • Projekt: Geben Sie Ihre Google Cloud-Projekt-ID aus dem Drop-down-Menü ein oder wählen Sie sie aus.

          • Region: In diesem Feld wird die Region Ihrer Verbindung vorab ausgewählt. Die angegebene Region für Ihren Dienst muss mit der Region übereinstimmen, die mit Ihrer Verbindung verknüpft ist.

        2. Namespace: Wählen Sie den Namespace Ihres Dienstes aus.

        3. Dienst: Wählen Sie den Dienstnamen in Ihrem Namespace aus.

  8. Klicken Sie auf Verbinden.

    Nachdem Sie auf die Schaltfläche Verbinden geklickt haben, werden Sie aufgefordert, eine GitHub-Anwendung in Ihrem GitHub Enterprise hostet und installiert die App in einem Nutzerkonto oder einer Organisation. Ein Authentifizierungstoken von Ihrem GitHub Enterprise-Host wird erstellt und in diesem Projekt als Secret Manager-Secret gespeichert. Sie können den Zugriff jederzeit widerrufen, indem Sie die GitHub-App von Ihrem Host deinstallieren oder löschen.

    Cloud Build speichert die Authentifizierungsdaten der erstellten GitHub-Anwendung als Secrets in Secret Manager in Ihrem Projekt Zu diesen Daten gehören Ihr privater Schlüssel und Ihr Webhook-Secret. Der private Schlüssel wird als Authentifizierungsmethode für den Zugriff auf die API verwendet des Enterprise Servers. Das Webhook-Secret wird verwendet, um die Ereignisse zu validieren, die vom Server an Cloud Build gesendet werden. Cloud Build Dienst-Agent-Konto (service-{projectNumber}@gcp-sa-cloudbuild.iam.gserviceaccount.com) wird verwendet, um auf Ihr Secret zuzugreifen. So rufen Sie Ihr Secret auf: Weitere Informationen finden Sie unter Secrets auflisten und Secret-Details ansehen.

    Nachdem Sie die Cloud Build-GitHub-Anwendung autorisiert haben, werden Sie zur Seite Repositories von Cloud Build weitergeleitet.

Sie haben jetzt eine GitHub Enterprise-Verbindung erstellt.

gcloud

So verbinden Sie Ihren GitHub Enterprise-Host mit Cloud Build mithilfe von gcloud-Befehle verwenden, führen Sie die folgenden Schritte aus:

  1. Geben Sie den folgenden Befehl ein, um eine GitHub Enterprise-Verbindung zu erstellen:

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

    Wobei:

    • CONNECTION_NAME ist der Name Ihrer Verbindung.
    • HOST_URI ist der URI Ihrer GitHub Enterprise-Instanz. Beispiel: https://mmy-ghe-server.net.
    • REGION ist die Region für Ihre Verbindung.

    Wenn sich Ihre GitHub Enterprise-Instanz in einem privaten Netzwerk befindet, geben Sie Ihren Service Directory-Ressource. Sie können auch Ihr CA-Zertifikat angeben.

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

    Wobei:

    • PROJECT_ID ist Ihre Google Cloud-Projekt-ID.
    • REGION ist die Region für Ihre Verbindung.
    • NAMESPACE ist der Namespace für Ihren Dienst.
    • SERVICE_NAME ist der Name des Dienstes in Ihrem Namespace.
    • SSL_CA_FILEPATH ist der Dateipfad zu Ihrem CA-Zertifikat.

    Nachdem Sie den Befehl gcloud builds connections... ausgeführt haben, führen Sie folgende Schritte aus: erhalten Sie einen Link zur Installation der GitHub-Anwendung von Cloud Build.

  2. Folgen Sie dem im vorherigen Schritt zurückgegebenen Link, um die Cloud Build-GitHub-App auf Ihrem Enterprise-Server zu erstellen und zu installieren.

  3. Geben Sie den folgenden Befehl ein, um die Verbindung zu prüfen:

    gcloud builds connections describe CONNECTION_NAME --region=REGION

    Wobei:

    • CONNECTION_NAME ist der Name Ihrer Verbindung.
    • REGION ist die Region für Ihre Verbindung.

    Wenn das Feld installationState auf COMPLETE gesetzt ist, wurde die Verbindung erfolgreich installiert. Andernfalls enthält das Feld installationState einen Link zu den erforderlichen zusätzlichen Schritten.

Sie haben jetzt eine GitHub Enterprise-Verbindung erstellt.

Programmatisch eine Verbindung zu einem GitHub Enterprise-Host herstellen

Wenn Sie Ihren GitHub Enterprise-Host programmatisch mit Cloud Build verbinden möchten, müssen Sie die GitHub-App installieren. Gehen Sie dazu so vor:

  1. Registrieren Sie eine neue GitHub-App. Sie können beispielsweise eine neue GitHub-App unter https://my-ghe-server.net/settings/apps/new registrieren.

  2. Füllen Sie die Felder auf der Seite aus:

    1. GitHub-App-Name: Geben Sie einen Namen für Ihre Anwendung ein.
    2. Startseiten-URL: Geben Sie eine URL für Ihren GitHub Enterprise-Server ein.
    3. Entfernen Sie das Häkchen aus dem Kästchen für Nutzerautorisierungstokens ablaufen lassen.
    4. Führen Sie im Abschnitt Webhook die folgenden Schritte aus:
      • Aktiv: Setzen Sie ein Häkchen in das Kästchen, um Ihr Webook zu aktivieren.
      • Webhook-URL: Geben Sie Ihre Webhook-URL ein. Beispiel: https://cloudbuild.googleapis.com/v2/projects/{PROJECT_NUMBER}/locations/{REGION}/connections:processWebhook. Die Region in der Webhook-URL muss mit der Region Ihrer Verbindung übereinstimmen.
      • Webhook-Secret: Geben Sie einen zufällig generierten String ein und notieren Sie sich diesen.
    5. Geben Sie im Abschnitt Berechtigungen die folgenden Berechtigungen an:
      • Repository-Berechtigungen:
        • Prüfungen: Lesen und Schreiben
        • Inhalt: Lesen und Schreiben
        • Probleme: Schreibgeschützt
        • Metadata (schreibgeschützt)
        • Commit-Status: Schreibgeschützt
        • Pull-Anfragen: Schreibgeschützt
    6. Klicken Sie im Bereich Veranstaltungen abonnieren die folgenden Kästchen an:
      • Prüfung ausführen
      • Check Suite
      • Commit-Kommentar
      • Kommentar zum Problem senden
      • Pull-Anfrage
      • Kommentar zur Überprüfung einer Pull-Anfrage
      • Schieben
      • Repository
    7. Klicken Sie das Kästchen Beliebiges Konto an, damit Ihre GitHub-App von jedem Nutzer oder jeder Organisation installiert werden kann.

  3. Klicken Sie auf GitHub-App erstellen, um Ihre GitHub-App zu erstellen.

    Wenn Sie auf GitHub-App erstellen klicken, werden Sie zu Ihrer App-Seite weitergeleitet. Notieren Sie sich Ihre App-ID und den App-Slug. Der App-Slug befindet sich im letzten Segment der URL der Seite. z. B. https://my-ghe-server.net/settings/apps/{app-slug}.

  4. Klicken Sie im Bereich Private Schlüssel auf Privaten Schlüssel generieren.

    Speichern Sie die heruntergeladene Datei an einem sicheren Ort.

  5. Wählen Sie im linken Bereich App installieren aus.

    Wählen Sie den Nutzer oder die Organisation aus, für den bzw. die Sie die App installieren möchten. Notieren Sie sich nach der Installation der App die Installations-ID. Die Installations-ID befindet sich im letzten Segment der URL. der Seite. Beispiel: https://my-ghe-server.net/settings/installations/{installation-id}.

Nachdem Sie Ihre GitHub-Anwendung installiert haben, führen Sie die folgenden Schritte aus, um Ihren GitHub Enterprise-Host programmatisch über Terraform oder gcloud zu verbinden.

Terraform

Nachdem Sie die GitHub-Anwendung installiert haben, können Sie Ihren GitHub Enterprise-Host über den Google Terraform-Anbieter mit Cloud Build verbinden.

Im folgenden Beispiel führt das Code-Snippet Folgendes aus:

  • Konfiguriert den Terraform-Google-Anbieter
  • Erstellt ein Secret zum Speichern des privaten Schlüssels und des Webhook-Secrets der GitHub-Anwendung
  • Erteilt dem Cloud Build-Dienst-Agent die erforderlichen Berechtigungen für den Zugriff auf Secrets

  • Erstellt eine GitHub Enterprise-Verbindung

    // 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
    ]
}

Wobei:

  • PROJECT_ID ist Ihre Google Cloud-Projekt-ID.
  • PRIVATE_KEY_SECRET ist das Secret, das den privaten Schlüssel Ihrer GitHub-Anwendung enthält.
  • WEBHOOK_SECRET ist der Secret-Name, der den Secret-Wert des Webhooks Ihrer GitHub-Anwendung enthält.
  • WEBHOOK_SECRET_VALUE ist der Wert des Webhook-Secrets Ihrer GitHub-Anwendung.
  • REGION ist die Region für Ihre Verbindung.
  • CONNECTION_NAME ist der Name Ihrer GitHub-Verbindung.
  • URI ist der URI Ihrer Verbindung. Beispiel: https://my-github-enterprise-server.net.
  • APP_ID ist die ID Ihrer GitHub-Anwendung.
  • APP_SLUG ist der Slug der App. Beispiel: https://github.com/settings/apps/{app-slug}.
  • INSTALLATION_ID ist die Installations-ID Ihrer GitHub-Anwendung. Ihr Die Installations-ID finden Sie in der URL Ihres Cloud Build- GitHub-Anwendung, https://github.com/settings/installations/{installation-id}.

Sie haben jetzt eine GitHub Enterprise-Verbindung erstellt.

gcloud

Nachdem Sie die GitHub-App installiert haben, führen Sie die folgenden Schritte aus, um verbinden Sie Ihren GitHub Enterprise-Host programmatisch mithilfe von gcloud:

  1. So speichern Sie Ihre Secrets 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

    Wobei:

    • WEBHOOK_SECRET ist der String, den Sie für Ihr Webhook-Secret erstellt haben.
    • PRIVATE_KEY_FILE ist der Dateipfad zum privaten Schlüssel, den Sie generiert haben.

  2. Gewähren Sie dem Cloud Build-Dienst-Agent Zugriff auf Ihre Secrets:

    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"

    Wobei:

    • PROJECT_ID ist Ihre Google Cloud-Projekt-ID.
    • CLOUD_BUILD_SERVICE_AGENT ist Ihr Konto pro Produkt und Projekt.

  3. Erstellen Sie die GitHub Enterprise-Verbindung:

    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

    Wobei:

    • CONNECTION_NAME ist der Name Ihrer Verbindung.
    • HOST_URI ist der URI Ihrer GitHub Enterprise-Instanz. Beispiel: https://mmy-ghe-server.net.
    • APP_ID ist die ID Ihrer GitHub-Anwendung.
    • APP_SLUG ist der App-Slug. Beispiel: https://my-ghe-server.net/settings/apps/app-slug.
    • PROJECT_ID ist Ihre Google Cloud-Projekt-ID.
    • INSTALLATION_ID ist die Installations-ID Ihrer GitHub-Anwendung, z. B. https://my-ghe-server.net/settings/installations/installation-id.
    • REGION ist die Region für Ihre Verbindung.

    Wenn sich Ihre GitHub Enterprise-Instanz in einem privaten Netzwerk befindet, geben Sie die Ressource „Service Directory“ an. Sie können auch Ihr CA-Zertifikat angeben.

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

    Wobei:

    • PROJECT_ID ist Ihre Google Cloud-Projekt-ID.
    • REGION ist die Region für Ihre Verbindung.
    • NAMESPACE ist der Namespace Ihres Dienstes.
    • SERVICE_NAME ist der Name Ihres Dienstes in Ihrem Namespace.
    • SSL_CA_FILEPATH ist der Dateipfad zu Ihrem CA-Zertifikat.

Sie haben nun erfolgreich eine GitHub Enterprise-Verbindung erstellt.

Nächste Schritte