Mit einem GitHub-Repository verbinden

Auf dieser Seite wird erläutert, wie Sie ein GitHub-Repository mit Cloud Build verbinden. Weitere Informationen zu Cloud Build-Repositories finden Sie unter Cloud Build-Repositories.

Hinweis

  • Aktivieren Sie die Cloud Build API und die Secret Manager API.

    Rollen, die zum Aktivieren von APIs erforderlich sind

    Zum Aktivieren von APIs benötigen Sie die IAM-Rolle „Service Usage-Administrator“ (roles/serviceusage.serviceUsageAdmin), die die Berechtigung serviceusage.services.enable enthält. Weitere Informationen zum Zuweisen von Rollen

    APIs aktivieren

  • Halten Sie Ihren Quellcode in einem GitHub-Repository bereit.
  • Sie benötigen entweder eine Dockerfile oder eine Cloud Build-Konfigurationsdatei in Ihrem GitHub-Quell-Repository.
  • Wenn Sie Ihr Repository zum ersten Mal mit Cloud Build verbinden, benötigen Sie Berechtigungen auf Administratorebene für das Repository. Weitere Informationen zu GitHub-Repository-Berechtigungen finden Sie unter Repository-Berechtigungsstufen für eine Organisation.

  • Wenn Sie die gcloud-Befehle auf dieser Seite verwenden möchten, installieren Sie die Google Cloud CLI.

Verbindung zu einem GitHub-Host herstellen

Console

So verbinden Sie Ihr GitHub-Repository mit Cloud Build:

  1. Öffnen Sie in der Google 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 als Quellanbieter aus.

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

    • Region: Wählen Sie eine Region für Ihre Verbindung aus.

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

  7. Optional: Wenn Sie die Verschlüsselungsschlüssel verwalten möchten, die zum Verschlüsseln der Zugriffstokens für Ihre GitHub-Repositories verwendet werden, rufen Sie den Abschnitt Verschlüsselung auf und wählen Sie einen Cloud Key Management Service-Schlüssel aus. Weitere Informationen finden Sie unter Kundenverwaltete Verschlüsselungsschlüssel für Secret Manager aktivieren.

  8. Klicken Sie auf Verbinden.

    Nachdem Sie auf den Button Verbinden geklickt haben, werden Sie aufgefordert, die Cloud Build GitHub-App für den Zugriff auf Ihr GitHub-Konto zu autorisieren. Sie können den Zugriff auf die App jederzeit widerrufen, indem Sie die App von Ihrem Host deinstallieren oder löschen.

    Cloud Build fordert die Autorisierung Ihres GitHub-Nutzerkontos an und speichert das resultierende Autorisierungstoken als Secret in Secret Manager in Ihrem Projekt. Das Autorisierungstoken wird verwendet, um den Zugriff Ihres Nutzerkontos für die Installation der Cloud Build GitHub-App und für die verknüpften Repositories zu validieren. Das Cloud Build Service Agent-Konto (service-{projectNumber}@gcp-sa-cloudbuild.iam.gserviceaccount.com) wird verwendet, um auf Ihr Secret zuzugreifen. Informationen zum Aufrufen Ihres Secrets finden Sie unter Secrets auflisten und Secret-Details ansehen.

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

gcloud

Führen Sie die folgenden Schritte aus, um Ihren GitHub-Host mit gcloud zu verbinden:

  1. Geben Sie den folgenden Befehl ein, um eine Verbindung zu Ihrem GitHub-Repository herzustellen:

     gcloud builds connections create github CONNECTION_NAME --region=REGION

    Wobei:

    • CONNECTION_NAME ist ein Name für Ihre Verbindung, wie sie in Cloud Build angezeigt wird.

    • REGION ist die Region für Ihren Trigger.

    Nachdem Sie den Befehl gcloud builds connections ausgeführt haben, wird ein Link zum Autorisieren der Cloud Build-GitHub-App angezeigt.

  2. Melden Sie sich in Ihrem github.com-Konto an.

  3. Folgen Sie dem Link, um die Cloud Build-GitHub-App zu autorisieren.

    Nach der Autorisierung der App speichert Cloud Build ein Authentifizierungstoken als Secret im Secret Manager in Ihrem Google Cloud-Projekt. Sie können Ihre Secrets auf der Seite Secret Manager ansehen.

  4. Installieren Sie die Cloud Build GitHub App in Ihrem Konto oder in einem Konto einer Organisation, die Ihnen gehört.

    Lassen Sie die Installation über Ihr GitHub-Konto zu und wählen Sie bei Aufforderung die Repository-Berechtigungen aus.

  5. Prüfen Sie die Installation der GitHub-Verbindung mit dem folgenden Befehl:

     gcloud builds connections describe CONNECTION_NAME --region=REGION

    Wobei:

    • CONNECTION_NAME ist der Name Ihrer GitHub-Hostverbindung in Cloud Build.
    • REGION ist die Region für Ihren Trigger.

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

Programmatische Verbindung zu einem GitHub-Host herstellen

Wenn Sie programmatisch eine Verbindung zu einem GitHub-Host herstellen möchten, müssen Sie zuerst das Authentifizierungstoken für die Verbindung konfigurieren und dann die GitHub-Verbindung in Cloud Build erstellen.

Authentifizierungstoken konfigurieren

Wenn Sie programmatisch eine Verbindung zu einem GitHub-Host herstellen möchten, müssen Sie eine Cloud Build-GitHub-Verbindung erstellen, einschließlich eines Secrets für ein Authentifizierungstoken. Sie haben zwei Möglichkeiten, ein Authentifizierungstoken zu erhalten:

  • Erstellen Sie ein persönliches Zugriffstoken in GitHub.

  • Verwenden Sie ein Token aus einer vorhandenen Cloud Build-GitHub-Verbindung. Diese Methode ist hilfreich, wenn für Ihr GitHub-Konto Einschränkungen gelten, die das Erstellen persönlicher Zugriffstokens verhindern. Wenn Sie außerdem beim Erstellen einer Verbindung über ein Skript auf dieses Token verweisen, müssen Sie die Verbindung nicht manuell über einen Webbrowser authentifizieren.

Persönliches Zugriffstoken

  1. Folgen Sie der Anleitung in der GitHub-Dokumentation, um ein persönliches Zugriffstoken zu erstellen.

  2. Wählen Sie die folgenden OAuth-Bereiche aus, wenn Sie in GitHub dazu aufgefordert werden:

    • repo, um vollständigen Zugriff auf öffentliche und private Repositories zu gewähren.
    • read:user, um Zugriff zum Lesen der Profildaten eines Nutzers zu gewähren.
    • read:org für den Nur-Lesezugriff auf die Organisationsmitgliedschaft und Projekte (wenn Ihre App in einer Organisation installiert ist).

  3. Speichern Sie den Wert Ihres persönlichen Zugriffstokens. Sie benötigen ihn später wieder.

Vorhandene Verbindung

  1. Führen Sie den folgenden Befehl in der gcloud CLI aus:

    gcloud builds connections describe CONNECTION_NAME --region=REGION

    Wobei:

    • CONNECTION_NAME ist der Name Ihrer GitHub-Hostverbindung.
    • REGION ist die Region für Ihren Trigger.

  2. In der Befehlsausgabe ist der Wert von authorizerTokenSecretVersion die ID des Secrets, das das Authentifizierungstoken der Verbindung enthält. Kopieren Sie diesen Wert und speichern Sie ihn an einem sicheren Ort. Sie benötigen das generierte Token für die folgenden Schritte.

GitHub-Verbindung erstellen

Erstellen Sie eine GitHub-Verbindung mit Terraform oder der gcloud CLI.

Terraform

Sie können Ihren GitHub-Host mit Cloud Build verbinden, indem Sie den Google Terraform-Provider verwenden und die folgenden Schritte ausführen:

  1. Installieren Sie die Cloud Build GitHub App in Ihrem GitHub-Konto oder in einem Konto einer Organisation, die Ihnen gehört.

  2. Konfigurieren Sie Ihre GitHub-Verbindung in Terraform. Das folgende Terraform-Codebeispiel zeigt eine Konfiguration, die Folgendes ausführt:

    • Konfiguriert den Terraform Google-Anbieter

    • Erstellt ein Secret zum Speichern persönlicher GitHub-Zugriffstokens

    • Erteilt dem Cloud Build-Dienst-Agent Berechtigungen für den Zugriff auf das Secret

    • Erstellt eine GitHub-Verbindung

    // Configure the terraform google provider
terraform {
  required_providers {
    google = {}
    }
}

// Create a secret containing the personal access token and grant permissions to the Service Agent
resource "google_secret_manager_secret" "github_token_secret" {
    project = PROJECT_ID
    secret_id = SECRET_ID

    replication {
        auto {}
    }
}

resource "google_secret_manager_secret_version" "github_token_secret_version" {
    secret = google_secret_manager_secret.github_token_secret.id
    secret_data = GITHUB_PAT
}

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" {
  project = google_secret_manager_secret.github_token_secret.project
  secret_id = google_secret_manager_secret.github_token_secret.secret_id
  policy_data = data.google_iam_policy.serviceagent_secretAccessor.policy_data
}

// Create the GitHub connection
resource "google_cloudbuildv2_connection" "my_connection" {
    project = PROJECT_ID
    location = REGION
    name = CONNECTION_NAME

    github_config {
        app_installation_id = INSTALLATION_ID
        authorizer_credential {
            oauth_token_secret_version = google_secret_manager_secret_version.github_token_secret_version.id
        }
    }
    depends_on = [google_secret_manager_secret_iam_policy.policy]
}

Wobei:

  • PROJECT_NUMBER ist die Google Cloud Projektnummer.
  • SECRET_ID ist die ID Ihres persönlichen GitHub-Zugriffstokens oder Ihres Secrets in Secret Manager.
  • GITHUB_PAT ist das Zugriffstoken des persönlichen Zugriffstokens in GitHub.
  • PROJECT_ID ist die Google Cloud Projekt-ID.
  • REGION ist die Region für Ihre Verbindung.
  • CONNECTION_NAME ist ein Name für Ihre Verbindung, wie sie in Cloud Build angezeigt wird.
  • INSTALLATION_ID ist die Installations-ID Ihrer Cloud Build-GitHub-App. Sie finden die Installations-ID in der URL Ihrer Cloud Build-GitHub-App. In der folgenden URL https://github.com/settings/installations/1234567 ist die Installations-ID der numerische Wert 1234567.

gcloud

So verbinden Sie Ihren GitHub-Host mit Cloud Build:

  1. Installieren Sie die Cloud Build GitHub App in Ihrem GitHub-Konto oder in einem Konto einer Organisation, die Ihnen gehört.

  2. Optional. Wenn Sie ein persönliches GitHub-Zugriffstoken für die Authentifizierung verwenden, führen Sie den folgenden Befehl aus, um das Token in Secret Manager in Ihrem Google Cloud -Projekt zu speichern:

    echo -n 'TOKEN' | gcloud secrets create SECRET_NAME --data-file=-

  3. Gewähren Sie dem Cloud Build-Dienst-Agent Zugriff auf das Secret. Dabei ist SECRET_NAME der Name Ihres Secrets, wie es in Secret Manager gespeichert ist:

    PROJECT_ID=$(gcloud config list --format="value(core.project)")
PN=$(gcloud projects describe ${PROJECT_ID} --format="value(projectNumber)")
CLOUD_BUILD_SERVICE_AGENT="service-${PN}@gcp-sa-cloudbuild.iam.gserviceaccount.com"
gcloud secrets add-iam-policy-binding SECRET_NAME \
  --member="serviceAccount:${CLOUD_BUILD_SERVICE_AGENT}" \
  --role="roles/secretmanager.secretAccessor"

  4. GitHub-Verbindung erstellen:

    gcloud builds connections create github CONNECTION_NAME \
  --authorizer-token-secret-version=projects/PROJECT_ID/secrets/SECRET_NAME/versions/VERSION  \
  --app-installation-id=INSTALLATION_ID --region=REGION

    Wobei:

    • CONNECTION_NAME ist der Name Ihrer GitHub-Hostverbindung in Cloud Build.
    • PROJECT_ID ist die Google Cloud Projekt-ID.
    • SECRET_NAME ist der Name des Secrets, wie es im Secret Manager gespeichert ist.
    • VERSION ist die Version Ihres Secrets.
    • INSTALLATION_ID ist die Installations-ID Ihrer GitHub-App. Sie finden die Installations-ID in der URL Ihrer Cloud Build-GitHub-App. In der folgenden URL https://github.com/settings/installations/1234567 ist die Installations-ID der numerische Wert 1234567.
    • REGION ist die Region Ihrer Verbindung.

GitHub-Repository verbinden

Console

So verbinden Sie ein GitHub-Repository mit einer Hostverbindung:

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

    Zur Seite „Repositories“

    Die Seite Repositories wird angezeigt.

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

  3. Klicken Sie auf Repositories verknüpfen, um Repositories aus Ihrer Verbindung zu verknüpfen.

    Das Feld Repositories verbinden wird angezeigt.

  4. Geben Sie im Bereich Repositories verbinden die folgenden Informationen ein:

    1. Verbindung: Wählen Sie im Drop-down-Menü eine Verbindung aus.

    2. Repository: Wählen Sie ein Repository aus, das mit Ihrer Verbindung verknüpft werden soll.

    3. Repository-Name: Geben Sie einen Namen für das Repository ein.

      1. Generiert: Wählen Sie diese Option aus, damit Cloud Build automatisch Repository-Namen für ausgewählte Repositories generiert.

      2. Manuell: Wählen Sie diese Option aus, um Namen für die ausgewählten Repositories manuell anzugeben.

        Wenn Sie Manuell auswählen, können Sie die Namen für die ausgewählten Repositories im Abschnitt Repository-Namen ändern.

  5. Klicken Sie auf Link, um Ihr Repository mit Ihrer Verbindung zu verknüpfen.

gcloud

Geben Sie den folgenden Befehl ein, um Ihrer Verbindung ein GitHub-Repository hinzuzufügen:

   gcloud builds repositories create REPO_NAME \
     --remote-uri=REPO_URI \
     --connection=CONNECTION_NAME --region=REGION

Wobei:

  • REPO_NAME ist der Name Ihres Repositorys.
  • REPO_URI ist der Link zu Ihrem GitHub-Repository. Beispiel: https://github.com/cloud-build/test-repo.git
  • CONNECTION_NAME ist der Name der GitHub Enterprise-Hostverbindung, die in Cloud Build über Mit einem GitHub-Host verbinden erstellt wurde.
  • REGION ist die Region für Ihre Verbindung.

Terraform

Wenn Sie Ihrer Verbindung ein GitHub-Repository hinzufügen möchten, fügen Sie Ihrer Terraform-Konfiguration den folgenden Code-Snippet hinzu:

    resource "google_cloudbuildv2_repository" "my_repository" {
      project = "PROJECT_ID"
      location = "REGION"
      name = "REPO_NAME"
      parent_connection = google_cloudbuildv2_connection.my_connection.name
      remote_uri = "URI"
  }

Wobei:

  • PROJECT_ID ist die Google Cloud Projekt-ID.
  • REPO_NAME ist der Name Ihres GitHub-Repositorys.
  • REGION ist die Region für Ihre Verbindung.
  • URI ist der Host-URI Ihres Repositorys. Beispiel: https://github.com/myuser/myrepo.git

Nächste Schritte