Builds als Reaktion auf Webhook-Ereignisse automatisieren

1. Generation 2. Generation

Mit Cloud Build können Sie Webhook-Trigger definieren, die eingehende Webhook-Ereignisse authentifizieren und akzeptieren. Mit diesen Ereignissen, die an eine benutzerdefinierte URL gesendet werden, können Sie externe Systeme und externe Quellcodeverwaltungssysteme wie Bitbucket.com, Bitbucket Server oder GitLab über Webhook-Ereignisse direkt mit Cloud Build verbinden.

Mit Webhook-Triggern können Sie eine Inline-Build-Konfigurationsdatei definieren, anstatt beim Erstellen des Triggers eine Quelle anzugeben. Mit der Inline-Build-Konfiguration können Sie die Git-Vorgänge steuern und den Rest des Builds definieren.

Auf dieser Seite wird beschrieben, wie Sie Webhook-Trigger erstellen, um Builds als Reaktion auf Webhook-Ereignisse zu automatisieren.

Hinweis: Wenn Sie einen Trigger erstellen, der Builds bei Repository-Ereignissen automatisiert, empfehlen die Verwendung von Cloud Build-Repository-Triggern. Repository-Trigger, die Cloud Build-Repositories (2. Generation) verwenden, können programmatisch konfiguriert werden und sind nativ in Quellanbieter integriert. Derzeit wird GitHub und GitLab unterstützt. Cloud Build-Repositories (2. Generation) verwalten mit Secret Manager auch Authentifizierungstokens und -informationen in Ihrem Namen. Repository-Trigger ermöglichen das einfache Filtern eingehender Ereignisse und den Status nach dem Build an den Quellanbieter zurück. Sie können auch so konfiguriert werden, dass sie mit einem privaten Netzwerk funktionieren. Weitere Informationen finden Sie auf der Seite Repositories – Übersicht.

Hinweise

• Enable the Cloud Build and Secret Manager APIs.

  Enable the APIs

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

  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.

Webhook-Trigger erstellen

Console

So erstellen Sie einen Webhook-Trigger mit der Google Cloud Console:

1. Seite "Trigger" aufrufen

   Zur Seite "Build-Trigger"

2. Wählen Sie das Projekt oben auf der Seite aus und klicken Sie auf Öffnen.

3. Klicken Sie auf Trigger erstellen.

4. Geben Sie die folgenden Triggereinstellungen ein:

   • Name: Ein Name für Ihren Trigger

   • Region: Wählen Sie die Region für den Trigger aus.

     • Wenn in der Build-Konfigurationsdatei, die mit dem Trigger verknüpft ist, ein privater Pool angegeben ist, verwendet Cloud Build den privaten Pool, um den Build auszuführen. In diesem Fall muss die Region, die Sie in Ihrem Trigger angeben, mit der Region übereinstimmen, in der Sie Ihren privaten Pool erstellt haben.
     • Wenn die mit dem Trigger verknüpfte Build-Konfigurationsdatei keinen privaten Pool angibt. Cloud Build verwendet die Standardeinstellung Pool, um den Build in derselben Region auszuführen als Trigger festlegen.

   • Beschreibung Optional: Eine Beschreibung für Ihren Trigger.

   • Ereignis: Wählen Sie Webhook-Ereignis aus, um den Trigger so einzurichten, dass Builds als Reaktion auf eingehende Webhook-Ereignisse starten.

   • Webhook-URL: Verwenden Sie die Webhook-URL, um eingehende Webhook-Ereignisse zu authentifizieren.

     • Secret: Sie benötigen ein Secret für die Authentifizierung eingehender Webhook-Ereignisse. Sie können ein neues Secret erstellen oder ein vorhandenes verwenden. Dieses Secret ist unabhängig vom Secret, das mit Ihrem SSH-Schlüssel verknüpft ist.

       So erstellen Sie ein neues Secret:

       1. Wählen Sie Neues Secret verwenden (von Cloud Build generiert) aus.

       2. Klicken Sie auf Secret erstellen.

          Das Pop-up-Fenster Webhook-Secret erstellen wird angezeigt.

       3. Geben Sie im Feld Secret-Name einen Namen für Ihr Secret ein.

       4. Klicken Sie auf Secret erstellen, um Ihr Secret zu speichern. Es wird automatisch im Secret Manager erstellt und gespeichert.

       So verwenden Sie ein vorhandenes Secret:

       1. Wählen Sie Vorhandenes Secret verwenden oder eigenes erstellen aus.
       2. Wählen Sie im Feld Secret den Namen des Secrets aus dem Drop-down-Menü aus oder folgen Sie der Anleitung, um ein Secret nach Ressourcen-ID hinzuzufügen.
       3. Wählen Sie im Feld Secret-Version Ihre Secret-Version aus dem Drop-down-Menü aus.

       Wenn Sie ein vorhandenes Secret verwenden, müssen Sie dem Cloud Build-Dienstkonto service-${PROJECT_NUMBER}@gcp-sa-cloudbuild.iam.gserviceaccount.com möglicherweise die Rolle Zugriffsperson für Secret Manager-Secret manuell zuweisen. Weitere Informationen finden Sie unter Dienstkonto die Rolle Secret Manager zuweisen.

     Nachdem Sie Ihr Secret erstellt oder ausgewählt haben, wird eine Webhook-URL-Vorschau angezeigt. Ihre URL enthält einen von Cloud Build und Ihrem Secret generierten API-Schlüssel. Wenn Cloud Build nicht in der Lage ist, Ihren API-Schlüssel abzurufen, können Sie Ihren API-Schlüssel manuell zur URL hinzufügen oder erfahren Sie, wie Sie einen API-Schlüssel erhalten, wenn Sie noch keinen haben.

     Sie können die URL verwenden, um ein Webhook-Ereignis aufzurufen. Erstellen Sie dazu eine HTTP-Anfrage mit der POST-Methode.

     Verwenden Sie den folgenden Befehl, um ein Webhook-Ereignis aufzurufen:

     curl -X POST -H "Content-type: application/json" "https://cloudbuild.googleapis.com/v1/projects/${PROJECT_ID}/locations/${REGION}/triggers/${TRIGGER_NAME}:webhook?key=${API_KEY}&secret=${SECRET_VALUE}&trigger=${TRIGGER_NAME}&projectId=${PROJECT_ID}" -d "{}"
     

     Nachdem Sie diese Schritte ausgeführt haben, zeigt der Secret Manager Rolle „Secret Accessor“ wird Ihrem Konto automatisch gewährt Cloud Build-Dienst-Agent service-${PROJECT_NUMBER}@gcp-sa-cloudbuild.iam.gserviceaccount.com Wenn diese Rolle nicht automatisch Ihrem Dienst-Agent hinzugefügt wird, führen Sie die folgenden Schritte aus, die unter Dienstkonto die Rolle Secret Manager zuweisen beschrieben werden.

   • Quelle (optional): Wählen Sie die Quelle aus, die beim Webhook-Trigger erstellt werden soll. ausgeführt wird. Wenn Sie eine Inline-Build-Konfiguration angeben, müssen Sie die folgende Quelle nicht angeben. Sie können 1. Generation oder 2. Generation als Quelle angeben. Weitere Informationen finden Sie unter Cloud Build-Repositories.

     Hinweis: Die Region Ihres Repositorys muss mit Die Region des Triggers.

     • Repository: Wählen Sie aus der Liste der verfügbaren Repositories das gewünschte Repository aus.

     • Zweig oder Tag: Geben Sie einen regulären Ausdruck mit dem abzugleichenden Zweig- oder Tag-Wert an. Informationen zur zulässigen Syntax für reguläre Ausdrücke finden Sie unter RE2-Syntax.

     • Kommentarsteuerung: Wenn Sie Pull-Anfrage (nur GitHub-App) als Ereignis ausgewählt haben, wählen Sie eine der folgenden Optionen aus, um zu kontrollieren, ob ein Build automatisch vom Trigger ausgeführt wird:

       Warnung: Jeder Nutzer mit Lesezugriff auf das Repository kann eine Pull-Anfrage senden, die möglicherweise einen Build ausführt, der Änderungen an der Quelle enthält. Code in der Pull-Anfrage. Wenn Sie dieses Verhalten deaktivieren möchten, empfehlen wir die Verwendung manueller Genehmigungen, um Builds zu steuern, wenn Sie Pull-Anfragen an öffentliche Repositories stellen. Weitere Informationen zu den Build-Berechtigungen für Trigger finden Sie hier.

       • Erforderlich, außer für Inhaber und Mitbearbeiter: Wenn eine Pull-Anfrage von einem Repository-Inhaber oder Mitbearbeiter erstellt oder aktualisiert wird, werden Builds automatisch vom Trigger ausgeführt. Wenn ein externer Mitwirkender die Aktion initiiert, werden Builds nur ausgeführt, nachdem ein Inhaber oder Mitbearbeiter /gcbrun zur Pull-Anfrage kommentiert hat.

       • Erforderlich: Wenn eine Pull-Anfrage von einem Mitwirkenden erstellt oder aktualisiert wird, werden Builds erst ausgeführt, nachdem ein Inhaber oder Mitbearbeiter /gcbrun zu der Pull-Anfrage kommentiert hat. Builds werden jedes Mal ausgeführt, wenn eine Änderung an einem Pull-Request vorgenommen wird.

       • Nicht erforderlich: Wenn eine Pull-Anfrage von einem Mitwirkenden erstellt oder aktualisiert wird, werden Builds automatisch durch Trigger ausgeführt.

   • Konfiguration: Wählen Sie die Build-Konfigurationsdatei aus, die sich in Ihrem Remote-Repository befindet, oder erstellen Sie eine Inline-Build-Konfigurationsdatei für den Build. Wenn Sie kein Quell-Repository angegeben haben, müssen Sie eine Inline-Build-Konfigurationsdatei als Konfigurationsoption auswählen.

     • Typ: Wählen Sie den Konfigurationstyp aus, der für Ihren Build verwendet werden soll.
       • Cloud Build-Konfigurationsdatei (YAML oder JSON): Verwenden Sie eine Build-Konfigurationsdatei für Ihre Konfiguration.
       • Dockerfile: Verwenden Sie für Ihre Konfiguration eine Dockerfile.
       • Buildpacks: Verwenden Sie Buildpacks für Ihre Konfiguration.

     • Speicherort: Geben Sie den Speicherort für Ihre Konfiguration an.

       • Repository: Wenn sich die Konfigurationsdatei in Ihrem Remote-Repository befindet, geben Sie den Speicherort Ihrer Build-Konfigurationsdatei, das Verzeichnis der Dockerfile oder das Verzeichnis der Buildpacks an. Wenn Ihr Build-Konfigurationstyp eine Dockerfile oder ein Buildpack ist, müssen Sie einen Namen für das resultierende Image und optional ein Zeitlimit für den Build angeben. Wenn Sie den Image-Namen der Dockerfile oder des Buildpacks angegeben haben, sehen Sie eine Vorschau des Befehls docker build oder pack, den Ihr Build ausführen wird.
       • Buildpack-Umgebungsvariablen (Optional): Wenn Sie buildpacks als Konfigurationstyp ausgewählt haben, klicken Sie auf Pack-Umgebungsvariable hinzufügen, um Ihre Buildpack-Umgebungsvariablen und -werte anzugeben. Weitere Informationen zu Buildpack-Umgebungsvariablen finden Sie unter Umgebungsvariablen.

       • Inline: Wenn Sie die Cloud Build-Konfigurationsdatei (YAML oder JSON) als Konfigurationsoption ausgewählt haben, können Sie die Build-Konfiguration inline angeben. Klicken Sie auf Editor öffnen, um Ihre Build-Konfigurationsdatei in der Google Cloud Console in der YAML- oder JSON-Syntax zu schreiben. Klicken Sie auf Fertig, um die Build-Konfiguration zu speichern.

         Hinweis: Die Unterstützung der Inline-Build-Konfiguration ist für Dockerfile oder Buildpacks nicht verfügbar.

     Im folgenden Beispiel gibt die Inline-Build-Konfigurationsdateilogs "hello world" zurück:

      steps:
      - name: 'ubuntu'
        args: ['echo', 'hello world']
     

   • Substitutionen (optional): Wenn Sie die Build-Konfigurationsdatei als Ihre Build-Konfigurationsoption ausgewählt oder eine Inline-Build-Konfigurationsdatei erstellt haben, können Sie in diesem Feld trigger-spezifische Substitutionsvariablen definieren. Sie können Daten auch mit Nutzlastbindungen abrufen, wenn Sie Werte für Substitutionsvariablen definieren.

   • Filter (optional): Sie können eine Regel innerhalb eines Triggers erstellen, die festlegt, ob der Trigger einen Build auf der Grundlage Ihrer Substitutionsvariablen ausführt.

5. Klicken Sie auf Erstellen, um den Build-Trigger zu erstellen.

gcloud

Vorschau — Webhook triggers: Cloud Build repositories (2nd gen) support

Diese Funktion unterliegt den „Nutzungsbedingungen für Pre-GA-Angebote“ im Abschnitt „Allgemeine Nutzungsbedingungen“ der dienstspezifischen Nutzungsbedingungen. Sie können personenbezogene Daten für dieses Feature gemäß der Zusatz zur Verarbeitung von Cloud-Daten verarbeiten, vorbehaltlich der in der Vereinbarung beschriebenen Verpflichtungen und Einschränkungen, die für den Zugriff auf Google Cloud gelten. Pre-GA-Funktionen sind „wie besehen“ verfügbar und werden möglicherweise nur eingeschränkt unterstützt. Weitere Informationen finden Sie in den Beschreibungen der Startphase.

So erstellen Sie einen Webhook-Trigger:

gcloud builds triggers create webhook \
  --region=REGION \
  --name=TRIGGER_NAME \
  --repository=projects/PROJECT_ID/locations/REGION/connections/CONNECTION_NAME/repositories/REPO_NAME \
  --secret=projects/PROJECT_ID/secrets/SECRET_NAME/versions/SECRET_VERSION \
  --substitutions=_SUB_ONE='$(body.message.test)',_SUB_TWO='$(body.message.output)' \
  --subscription-filter='_SUB_ONE == "prod"' \
  --inline-config=PATH_TO_INLINE_BUILD_CONFIG \
  --tag=TAG_NAME
  # --build-config=PATH_TO_BUILD_CONFIG \
  # --branch=BRANCH_NAME

Wobei:

• REGION ist die Region für den Trigger.
• TRIGGER_NAME ist der Name des Triggers.
• PROJECT_ID ist die ID Ihres Cloud-Projekts.
• CONNECTION_NAME ist der Name Ihrer Hostverbindung.
• REPO_NAME ist der Name Ihres Repositorys.
• SECRET_NAME ist der Name Ihres Secrets, wie er in folgendem Verzeichnis gespeichert ist: Secret Manager
• SECRET_VERSION ist die Version, die mit Ihrem wie in Secret Manager gespeichert.
• PATH_TO_INLINE_BUILD_CONFIG ist der Pfad zu Ihrer Inline-Build-Konfigurationsdatei, wenn Sie --inline-config verwenden.
• TAG_NAME ist der Name Ihres Tags, wenn Sie den Trigger auf einem Tag aufbauen möchten.
• PATH_TO_BUILD_CONFIG ist der Pfad zu Ihrer Build-Konfigurationsdatei, wenn Sie --build-config verwenden.
• BRANCH_NAME ist der Name Ihres Zweigs, wenn Sie den Trigger auf einem Zweig erstellen möchten.

(Optional) API-Schlüssel abrufen

Sie benötigen einen API-Schlüssel, um ein eingehendes Webhook-Ereignis zu authentifizieren.

So erhalten Sie einen API-Schlüssel:

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

   Öffnen Sie die Seite Anmeldedaten

2. Klicken Sie auf Anmeldedaten erstellen.

3. Klicken Sie auf API-Schlüssel.

   Es wird ein Dialogfeld mit Ihrem erstellten API-Schlüssel angezeigt. Notieren Sie sich Ihren API-Schlüssel.

4. Wenn Sie Ihren Schlüssel für Produktanwendungen einschränken möchten, klicken Sie auf Schlüssel einschränken, um weitere Schritte zum Schutz Ihres Schlüssels auszuführen. Klicken Sie ansonsten auf Schließen.

   Informationen zum Einschränken Ihres Schlüssels finden Sie unter Einschränkungen für API-Schlüssel anwenden.

(Optional) Dienstkonto die Rolle Secret Manager zuweisen

Cloud Build weist Dienstkonten, die diese Rolle während der Secret-Konfiguration benötigen, automatisch die Rolle Zugriffsperson für Secret Manager-Secret zu. Wenn diese Rolle nicht automatisch dem erforderlichen Dienstkonto zugewiesen wird, führen Sie die folgenden Schritte aus, um die Rolle manuell hinzuzufügen, damit das Dienstkonto Zugriff auf das Secret hat:

1. Öffnen Sie in der Google Cloud Console die Seite „IAM“:

   Seite "IAM" öffnen

2. Optional: Wenn Sie von Google bereitgestellte Konten sehen möchten, klicken Sie auf das Kästchen Von Google bereitgestellte Rollenzuweisungen einschließen.

3. Notieren Sie sich das Build-Dienstkonto, das Sie verwenden möchten. dem die Rolle zugewiesen werden soll.

4. Öffnen Sie in der Google Cloud Console die Seite Secret Manager:

   Zur Seite "Secret Manager"

5. Klicken Sie auf den Namen Ihres Secrets.

   Es wird die Seite Secret-Details angezeigt.

   1. Klicken Sie auf den Tab Berechtigungen.

   2. Klicken Sie auf Zugriff gewähren.

      Der Bereich Zugriff gewähren wird angezeigt.

   3. Fügen Sie im Abschnitt Hauptkonten hinzufügen die E-Mail-Adresse hinzu, die mit dem Build-Dienstkonto verknüpft ist.

   4. Wählen Sie im Abschnitt Rollen zuweisen die Option Secret Manager > Zugriffsperson für Secret Manager-Secret aus.

   5. Klicken Sie auf Speichern.

Nächste Schritte

• Trigger erstellen und verwalten
• Auf Bitbucket Server gehostete Repositories erstellen
• Builds manuell starten
• Build-Ergebnisse aufrufen
• Build-Fehler beheben