Verbindung zu einem GitHub Enterprise-Host herstellen

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

Hinweise

  • Cloud Build and Secret Manager APIs aktivieren.

    Aktivieren Sie die APIs

Erforderliche IAM-Berechtigungen

Weisen Sie Ihrem Nutzerkonto die Rolle „Cloud Build Connection Admin“ (roles/cloudbuild.connectionAdmin) zu, um Ihren GitHub Enterprise-Host zu verbinden.

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

Zum Erstellen von Verbindungen mithilfe der Installationsschritte für gcloud weisen Sie dem Cloud Build-Dienst-Agent die Rolle „Secret Manager-Administrator“ (roles/secretmanager.admin) zu. Führen Sie dazu den folgenden Befehl in Ihrem Google Cloud-Projekt 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 von GitHub Enterprise in einem privaten Netzwerk erstellen weitere Informationen zu zusätzlichen IAM-Rollen, die vor der Hostverbindung erforderlich sind.

Verbindung zu einem GitHub Enterprise-Host herstellen

Console

So verbinden Sie den 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 2nd gen (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 Ihre Verbindung aus.

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

  7. Geben Sie im Abschnitt 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 Certificate (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 Ihre Instanz über das öffentliche Internet zugänglich ist.

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

      3. Wählen Sie unter Service Directory-Dienst den Speicherort 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 die folgenden Informationen ein:

          • 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 für Ihren Dienst angegebene Region muss mit der Region übereinstimmen, die Ihrer Verbindung zugeordnet 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-Host zu erstellen und in einem Nutzerkonto oder einer Organisation zu installieren. 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-Anwendung 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 des Enterprise Servers verwendet. Das Webhook-Secret wird verwendet, um die Ereignisse zu validieren, die vom Server an Cloud Build gesendet werden. Das Konto des Cloud Build-Dienst-Agents (service-{projectNumber}@gcp-sa-cloudbuild.iam.gserviceaccount.com) wird für den Zugriff auf Ihr Secret verwendet. Informationen zum Anzeigen von Secrets finden Sie unter Secrets auflisten und Secret-Details ansehen.

    Nach der Autorisierung der Cloud Build GitHub-Anwendung werden Sie zur Cloud Build-Seite Repositories weitergeleitet.

Sie haben jetzt erfolgreich eine GitHub Enterprise-Verbindung erstellt.

gcloud

Führen Sie die folgenden Schritte aus, um den GitHub Enterprise-Host mithilfe von gcloud-Befehlen mit Cloud Build zu verbinden:

  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 der 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 Ihre Service Directory-Ressource 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 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, erhalten Sie einen Link zur Installation der Cloud Build GitHub-Anwendung.

  2. Folgen Sie dem Link, der im vorherigen Schritt zurückgegeben wurde, um die Cloud Build-GitHub-Anwendung auf Ihrem Unternehmensserver zu erstellen und zu installieren.

  3. Geben Sie den folgenden Befehl ein, um die Verbindung zu überprü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, haben Sie die Verbindung erfolgreich installiert. Andernfalls enthält das Feld installationState einen Link für die zusätzlichen erforderlichen Schritte.

Sie haben jetzt erfolgreich eine GitHub Enterprise-Verbindung erstellt.

Programmatische 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-Anwendung installieren. Gehen Sie dazu so vor:

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

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

    1. GitHub App Name (Name der GitHub-Anwendung): Geben Sie einen Namen für die Anwendung ein.
    2. URL der Startseite: Geben Sie eine URL für Ihren GitHub Enterprise-Server ein.
    3. Entfernen Sie das Häkchen aus dem Kästchen Nutzerautorisierungstokens ablaufen.
    4. Führen Sie im Abschnitt Webhook die folgenden Schritte aus:
      • Aktiv: Setzen Sie ein Häkchen in das Kästchen, um Ihr book zu aktivieren.
      • Webhook URL (Webhook-URL): Geben Sie die 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 ihn.
    5. Geben Sie im Abschnitt Berechtigungen die folgenden Berechtigungen an:
      • Repository-Berechtigungen:
        • Checks: Lese- und Schreibzugriff
        • Inhalt: Lesen und Schreiben
        • Probleme: Schreibgeschützt
        • Metadaten (schreibgeschützt)
        • Commit-Status: Schreibgeschützt
        • Pull-Anfragen: Schreibgeschützt
    6. Klicken Sie im Bereich Ereignisse abonnieren die folgenden Kästchen an:
      • Ausführung prüfen
      • Suite prüfen
      • Commit-Kommentar
      • Kommentar zum Problem
      • Pull-Anfrage
      • Kommentar zur Überprüfung der Pull-Anfrage
      • Senden
      • Repository
    7. Klicken Sie das Kästchen Beliebiges Konto an, damit Ihre GitHub-Anwendung von jedem Nutzer oder jeder Organisation installiert werden kann.

  3. Klicken Sie auf GitHub-Anwendung erstellen, um die GitHub-Anwendung zu erstellen.

    Wenn Sie auf GitHub-Anwendung erstellen klicken, werden Sie zur Seite der Anwendung weitergeleitet. Notieren Sie sich Ihre App-ID und den App-Slug. Die 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 Abschnitt 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 die Sie die App installieren möchten. Notieren Sie sich nach der Installation die Installations-ID. Die Installations-ID finden Sie im letzten Segment der URL der Seite. Beispiel: https://my-ghe-server.net/settings/installations/{installation-id}.

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

Terraform

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

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

  • Konfiguriert den Google-Anbieter für Terraform
  • Erstellt ein Secret zum Speichern des privaten Schlüssels und des Webhook-Secrets der GitHub-Anwendung
  • Gewährt 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 {
        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
    ]
}

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 Name des Secrets, das den Webhook-Secret-Wert 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 der GitHub-Verbindung.
  • URI ist der URI der Verbindung. Beispiel: https://my-github-enterprise-server.net.
  • APP_ID ist die ID der GitHub-Anwendung.
  • APP_SLUG ist der App-Slug. Beispiel: https://github.com/settings/apps/{app-slug}.
  • INSTALLATION_ID ist die Installations-ID der GitHub-Anwendung. Sie finden die Installations-ID in der URL der Cloud Build-GitHub-Anwendung https://github.com/settings/installations/{installation-id}.

Sie haben jetzt erfolgreich eine GitHub Enterprise-Verbindung erstellt.

gcloud

Nachdem Sie die GitHub-Anwendung installiert haben, führen Sie die folgenden Schritte aus, um mit gcloud programmatisch eine Verbindung zu Ihrem GitHub Enterprise-Host herzustellen:

  1. 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 der GitHub Enterprise-Instanz. Beispiel: https://mmy-ghe-server.net.
    • APP_ID ist die ID der 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 der GitHub-Anwendung. Beispiel: 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 Ihre Service Directory-Ressource 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 des Dienstes in Ihrem Namespace.
    • SSL_CA_FILEPATH ist der Dateipfad zu Ihrem CA-Zertifikat.

Sie haben jetzt erfolgreich eine GitHub Enterprise-Verbindung erstellt.

Nächste Schritte