Mit einem GitHub-Repository verbinden

1. Generation 2. Generation

Auf dieser Seite wird beschrieben, 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.

  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. Informationen zum Zuweisen von Rollen.

  API aktivieren

• Halten Sie Ihren Quellcode in einem GitHub-Repository bereit.
• Sie benötigen entweder eine Dockerfile-Datei 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 auf dieser Seite gcloud-Befehle verwenden möchten, installieren Sie die Google Cloud CLI.

  Hinweis: Wenn Sie die gcloud CLI bereits installiert haben, prüfen Sie, ob Sie die neueste verfügbare Version nutzen. Führen Sie dazu gcloud components update aus.

Erforderliche IAM-Berechtigungen

Zum Verbinden Ihres GitHub-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. Weitere Informationen zu IAM-Rollen, die mit Cloud Build verknüpft sind, finden Sie unter IAM-Rollen und -Berechtigungen.

Wenn Sie Verbindungen mit den gcloud Installationsschritten erstellen möchten, 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"

Hinweis: Sie können die Rolle „Secret Manager-Administrator“ (roles/secretmanager.admin) widerrufen, nachdem die Verbindung den Status COMPLETE hat. Weitere Informationen finden Sie unter Cloud Build-Dienst-Agent eine Rolle zuweisen.

Mit einem GitHub-Host verbinden

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 die Verbindung aus.

     Hinweis: Sie müssen eine Region angeben. Die Verbindung kann nicht global sein.

   • 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 die Schaltfläche 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-Dienst-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.

   Hinweis: Diese Authentifizierung kann verwendet werden, um zusätzliche Verbindungen im selben Projekt zu erstellen. Wir empfehlen, anstelle eines persönlichen GitHub-Kontos ein Robot-Konto oder ein Konto zu verwenden, das von Ihrem Team gemeinsam genutzt wird, um Ihre Verbindungen zu schützen.

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

gcloud

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

Hinweis: Für die Installationsschritte sind Aktionen in Ihrem Webbrowser erforderlich.

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 die Verbindung, wie sie in Cloud Build angezeigt wird.

   • REGION ist die Region für den Trigger.

     Hinweis: Sie müssen eine Region angeben. Die Verbindung kann nicht global sein.

   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.

   Hinweis: Diese Authentifizierung kann verwendet werden, um zusätzliche Verbindungen im selben Projekt zu erstellen. Wir empfehlen, anstelle eines persönlichen GitHub-Kontos ein Robot-Konto oder ein Konto zu verwenden, das von Ihrem Team gemeinsam genutzt wird, um Ihre Verbindungen zu schützen.

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

   Nachdem Sie die App autorisiert haben, speichert Cloud Build ein Authentifizierung token als Secret in Secret Manager in Ihrem Google Cloud Projekt. Sie können Ihre Secrets auf der Secret Manager Seite 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 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 der GitHub-Hostverbindung in Cloud Build.
   • REGION ist die Region für den Trigger.

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

Programmatisch mit einem GitHub-Host verbinden

Terraform

Sie können Ihren GitHub-Host mit Cloud Build über den Google Terraform-Anbieter verbinden. Führen Sie dazu die folgenden Schritte aus:

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

2. Erstellen Sie ein persönliches Zugriffstoken.

   Legen Sie für das Token kein Ablaufdatum fest. Wenn Sie ein detailliertes Token erstellen, wählen Sie die für Ihre Anforderungen erforderlichen Mindestberechtigungen aus. Wenn Sie ein klassisches Token erstellen, wählen Sie die folgenden OAuth-Bereiche bei Aufforderung in GitHub aus:

   • 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 Lesezugriff auf die Mitgliedschaft und Projekte der Organisation (wenn Ihre App in einer Organisation installiert ist).

   Nachdem Sie Ihr persönliches Zugriffstoken generiert haben, speichern Sie es an einem sicheren Ort. Sie verwenden das generierte Token in den folgenden Schritten.

   Hinweis: Wenn Sie ein Authentifizierungstoken in einem Secret aus einer zuvor erstellten Verbindung gespeichert haben, können Sie dasselbe Secret für die neue Verbindung verwenden.

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

• Konfiguriert den Terraform Google-Anbieter

• Erstellt ein Secret zum Speichern persönlicher GitHub-Zugriffstokens, um dem Cloud Build-Dienst-Agent Berechtigungen für den Zugriff auf das Secret zu gewähren

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

gcloud

Führen Sie die folgenden Schritte aus, um Ihren GitHub-Host mit einem vorhandenen Token und einer vorhandenen Installations-ID aus einer vorherigen Verbindung zu verbinden:

**Hinweis**: Wenn Sie ein vorhandenes Token und eine Installations-ID verwenden, um eine Verbindung herzustellen, z. B. über ein Skript, ist keine manuelle Interaktion über einen Webbrowser erforderlich.

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

2. Erstellen Sie ein persönliches Zugriffstoken.

   Legen Sie für das Token kein Ablaufdatum fest. Wenn Sie ein detailliertes Token erstellen, wählen Sie die für Ihre Anforderungen erforderlichen Mindestberechtigungen aus. Wenn Sie ein klassisches Token erstellen, wählen Sie die folgenden OAuth-Bereiche bei Aufforderung in GitHub aus:

   • 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 Lesezugriff auf die Mitgliedschaft und Projekte der Organisation (wenn Ihre App in einer Organisation installiert ist).

   Nachdem Sie Ihr persönliches Zugriffstoken generiert haben, speichern Sie es an einem sicheren Ort. Sie verwenden das generierte Token in den folgenden Schritten.

   Hinweis: Wenn Sie ein Authentifizierungstoken in einem Secret aus einer zuvor erstellten Verbindung gespeichert haben, können Sie dasselbe Secret für die neue Verbindung verwenden.

3. Speichern Sie das Token in Secret Manager in Ihrem Google Cloud Projekt . Führen Sie dazu den folgenden Befehl aus:

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

   Wobei:

   • TOKEN ist Ihr persönliches Zugriffstoken.
   • SECRET_NAME ist der Name, den Sie Ihrem Secret in Secret Manager geben möchten.

4. Gewähren Sie dem Cloud Build-Dienst-Agent Zugriff auf das Secret. Dabei ist SECRET_NAME der Name des 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"
   

5. Erstellen Sie die GitHub-Verbindung:

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

   Wobei:

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

GitHub-Repository verbinden

Console

Führen Sie die folgenden Schritte aus, um ein GitHub-Repository mit einer Hostverbindung zu verbinden:

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 der Verbindung zu verknüpfen.

   Das Feld Repositories verbinden wird angezeigt.

4. Geben Sie im Feld 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 der 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 Verknüpfen , um das Repository mit der Verbindung zu verknüpfen.

gcloud

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

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

Wobei:

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

Terraform

Fügen Sie das folgende Code-Snippet zur Terraform-Konfiguration hinzu, um ein GitHub-Repository zur Verbindung hinzuzufügen:

    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 Ihre Google Cloud Projekt-ID.
• REPO_NAME ist der Name des GitHub-Repositorys.
• REGION ist die Region für die Verbindung.
• URI ist der Host-URI des Repositorys. Beispiel: https://github.com/myuser/myrepo.git.

Nächste Schritte

• Repositories von GitHub erstellen
• Blau/Grün-Bereitstellungen in der Compute Engine .
• Erfahren Sie, wie Sie zusätzliche Repositories als Abhängigkeiten für Ihren Build angeben.