Webhook-Trigger erstellen

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 können.

Hinweis

• Cloud Build and Secret Manager APIs aktivieren.

  Aktivieren Sie die APIs

• Installieren Sie das Cloud SDK, um gcloud-Befehle auf dieser Seite zu verwenden.

  Hinweis: Wenn Sie das Cloud SDK bereits installiert haben, prüfen Sie, ob Sie die neueste verfügbare Version haben. Führen Sie dazu den Befehl 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
   • 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.

       So erstellen Sie ein neues Secret:

       1. Wählen Sie Neu erstellen.

       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 Vorhandene verwenden 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 ${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.

      curl -X POST -H "application/json" "https://cloudbuild.googleapis.com/v1/projects/${PROJECT_NAME}/triggers/${TRIGGER_NAME}:webhook?key=${API_KEY}&secret=${SECRET_VALUE}" -d "{}"
     

     Nach Abschluss dieser Schritte wird Ihrem Cloud Build-Dienstkonto service-${PROJECT_NUMBER}@gcp-sa-cloudbuild.iam.gserviceaccount.com automatisch die Rolle Zugriffsperson für Secret Manager-Secret zugewiesen. Wenn diese Rolle nicht automatisch Ihrem Dienstkonto 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 das Repository aus, das bei Ausführung des Webhook-Triggers erstellt werden soll. Wenn Sie eine Inline-Build-Konfiguration angeben, müssen Sie die folgende Quelle nicht angeben.

   • Revision (optional): Wählen Sie den Zweig oder das Tag aus, der oder das erstellt werden soll, wenn der Webhook-Trigger ausgeführt wird. Wenn Sie eine Inline-Build-Konfiguration angeben, müssen Sie die folgenden Überarbeitungen nicht angeben.

     • Zweig (optional): Legen Sie einen Trigger fest, der auf diesem Zweig erstellt werden soll. Sie müssen einen Literalwert angeben. Reguläre Ausdrücke werden nicht unterstützt.
     • Tag (optional): Legen Sie einen Trigger fest, der auf diesem Tag basiert. Sie müssen einen Literalwert angeben. Reguläre Ausdrücke werden nicht unterstützt.

   • 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 Ihre 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 YAML- oder JSON-Syntax in der Google Cloud Console 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.

     Eine Beispielsyntax für die Filterung, die Sie auf Ihre Webhook-Trigger anwenden können, finden Sie unter CEL zum Filtern von Build-Ereignissen verwenden.

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

gcloud

So erstellen Sie einen Webhook-Trigger:

gcloud alpha builds triggers create webhook \
  --name=TRIGGER_NAME \
  --repo=PATH_TO_REPO \
  --secret=PATH_TO_SECRET \
  --substitutions=_SUB_ONE='$(body.message.test)',_SUB_TWO='$(body.message.output)' \
  --filter='_SUB_ONE == "prod"' \
  --inline-config=PATH_TO_INLINE_BUILD_CONFIG \
  --tag=TAG_NAME
  # --build-config=PATH_TO_BUILD_CONFIG \
  # --branch=BRANCH_NAME

Warnung: Wenn Sie diesen gcloud-Befehl mit dem Flag --filter ausführen, wird möglicherweise der Fehler INVALID_ARGUMENT angezeigt. Der Webhook-Trigger kann immer noch erfolgreich erstellt werden. Führen Sie gcloud beta builds triggers list aus, um die Triggererstellung zu prüfen.

Wobei:

• TRIGGER_NAME ist der Name des Triggers.
• PATH_TO_REPO ist der Pfad zum Repository, für das ein Build aufgerufen werden soll. Beispiel: https://www.github.com/owner/repo.
• PATH_TO_SECRET ist der Pfad zum Secret, wie er im Secret Manager gespeichert ist. Beispiel: projects/my-project/secrets/my-secret/versions/2
• 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

Zur Authentifizierung des eingehenden Webhook-Ereignisses benötigen Sie einen API-Schlüssel.

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 Cloud Console die Seite "IAM".

   Seite "IAM" öffnen

2. Notieren Sie sich das Cloud Build-Dienstkonto, dem Sie die Rolle zuweisen möchten.

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

   Zur Seite "Secret Manager"

4. Klicken Sie auf den Namen Ihres Secrets.

   Es wird die Seite Secret-Details angezeigt.

   1. Klicken Sie im Infobereich auf der rechten Seite auf den Tab Berechtigungen.

   2. Klicken Sie auf Hauptkonto hinzufügen.

   3. Fügen Sie im Bereich Neues Hauptkonto die E-Mail-Adresse hinzu, die Ihrem Cloud Build-Dienstkonto zugeordnet ist.

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

   5. Klicken Sie auf Add.

Build-Ereignisse mit CEL filtern

Cloud Build verwendet CEL mit der Variablen build für Felder in der Ressource Build, um auf Felder zuzugreifen, die mit Ihrem Build-Ereignis verknüpft sind, z. B. Ihre Trigger-ID, Image-Liste oder Ersatzwerte. Sie können den String filter verwenden, um Build-Ereignisse in Ihrer Build-Konfigurationsdatei mit einem Feld zu filtern, das in der Ressource Build aufgeführt ist. Die genaue Syntax, die dem Feld zugeordnet ist, finden Sie in der Datei cloudbuild.proto.

Nach Trigger-ID filtern

Wenn Sie nach Trigger-ID filtern möchten, geben Sie den Wert Ihrer Trigger-ID im Feld filter mit build.build_trigger_id an. Dabei ist trigger-id Ihre Trigger-ID als String:

filter: build.build_trigger_id == trigger-id

Hinweis: Die Trigger-ID ist nichtder Name des Triggers. Führen Sie den folgenden Befehl aus, um die Trigger-ID abzurufen: gcloud beta builds triggers describe trigger-name, wobei trigger-name der Name Ihres Triggers ist. Der Befehl listet die Felder auf, die dem Trigger zugeordnet sind, einschließlich der Trigger-ID.

Nach Status filtern

Geben Sie im Feld filter mithilfe von build.status den Build-Status an, nach dem der Filter gefiltert werden soll.

Das folgende Beispiel zeigt, wie Sie Build-Ereignisse mit dem Status SUCCESS mithilfe des Felds filter filtern:

filter: build.status == Build.Status.SUCCESS

Sie können auch Builds mit unterschiedlichen Status filtern. Das folgende Beispiel zeigt, wie Build-Ereignisse mit dem Status SUCCESS, FAILURE oder TIMEOUT mit dem Feld filter gefiltert werden:

filter: build.status in [Build.Status.SUCCESS, Build.Status.FAILURE, Build.Status.TIMEOUT]

Weitere Statuswerte, nach denen Sie filtern können, finden Sie in der Referenz zu Build-Ressourcen unter Status.

Nach Tag filtern

Geben Sie zum Filtern nach Tag den Wert Ihres Tags im Feld filter mit build.tags ein, wobei tag-name der Name des Tags ist:

filter: tag-name in build.tags

Mit size können Sie nach der Anzahl der in Ihrem Build-Ereignis angegebenen Tags filtern. Im folgenden Beispiel filtert das Feld filter Build-Ereignisse, bei denen genau zwei Tags angegeben sind, wobei ein Tag als v1 angegeben ist:

filter: size(build.tags) == 2 && "v1" in build.tags

Nach Images filtern

Wenn Sie nach Images filtern möchten, geben Sie den Wert Ihres Images im Feld filter mit build.images an, wobei image-name der vollständige Name des Images ist, wie in Container Registry aufgeführt, z. B. gcr.io/example/image-one:

filter: image-name in build.images

Im folgenden Beispiel filtert filter nach Build-Ereignissen, in denen entweder gcr.io/example/image-one oder gcr.io/example/image-two als Bildnamen angegeben ist:

filter: "gcr.io/example/image-one" in build.images || "gcr.io/example/image-two" in build.images

Nach Zeitraum filtern

Sie können Build-Ereignisse nach der Erstellungszeit, dem Beginn oder dem Ende eines Builds filtern. Geben Sie dazu in Ihrem Feld filter eine der folgenden Optionen an: build.create_time, build.start_time oder build.finish_time zurück.

Im folgenden Beispiel verwendet das Feld filter timestamp, um Build-Ereignisse mit einer Anfragezeit zu filtern, um den Build am 20. Juli 2020 um 6:00 Uhr zu erstellen:

filter: build.create_time == timestamp("2020-07-20:T06:00:00Z")

Sie können Build-Ereignisse auch nach Zeitvergleichen filtern. Im folgenden Beispiel verwendet das Feld filter timestamp, um Build-Ereignisse mit einer Startzeit zwischen dem 20. Juli 2020, 6:00 Uhr und dem 30. Juli 2020 um 6:00 Uhr zu filtern. , um die Option zu aktivieren.

filter: timestamp("2020-07-20:T06:00:00Z") >= build.start_time && build.start_time <= timestamp("2020-07-30:T06:00:00Z")

Weitere Informationen dazu, wie Zeitzonen in CEL ausgedrückt werden, finden Sie in der Sprachdefinition für Zeitzonen.

Zum Filtern nach der Dauer eines Builds können Sie duration verwenden, um Zeitstempel zu vergleichen. Im folgenden Beispiel verwendet das Feld filter duration, um Build-Ereignisse mit Builds zu filtern, die mindestens fünf Minuten lang ausgeführt werden:

filter: build.finish_time - build.start_time >= duration("5m")

Hinweis: Zeitstempel werden im RFC 3339-UTC-"Zulu"-Format mit einer Auflösung im Nanosekundenbereich und bis zu neun Nachkommastellen angegeben.

Nach Substitution filtern

Sie können nach Substitution filtern, wenn Sie die Substitutionsvariable im Feld filter mit build.substitutions angeben. Im folgenden Beispiel listet das Feld filter Builds auf, die die Substitutionsvariable substitution-variable enthalten, und prüft, ob substitution-variable mit dem angegebenen substitution-value übereinstimmt:

filter: build.substitutions[substitution-variable] == substitution-value

Hierbei gilt:

• substitution-variable ist der Name der Substitutionsvariablen.
• substitution-value ist der Name Ihres Substitutionswerts.

Sie können auch nach Standardwerten für Substitutionsvariablen filtern. Im folgenden Beispiel werden im Feld filter Builds mit dem Zweignamen master und Builds mit dem Repository-Namen github.com/user/my-example-repo aufgelistet. Die Standardsubstitutionsvariablen BRANCH_NAME und REPO_NAME werden als Schlüssel an build.substitutions übergeben:

filter: build.substitutions["BRANCH_NAME"] == "master" && build.substitutions["REPO_NAME"] == "github.com/user/my-example-repo"

Wenn Sie mithilfe von regulären Ausdrücken nach Strings filtern möchten, können Sie die integrierte Funktion matches verwenden. Im folgenden Beispiel filtert das Feld filter nach Builds mit dem Status FAILURE oder TIMEOUT und einer Build-Substitutionsvariablen TAG_NAME mit einem Wert, der dem regulären Ausdruck v{DIGIT}.{DIGIT}.{3 DIGITS}) entspricht.

filter: build.status in [Build.Status.FAILURE, Build.Status.TIMEOUT] && build.substitutions["TAG_NAME"].matches("^v\\d{1}\\.\\d{1}\\.\\d{3}$")`

Eine Liste der Standardsubstitutionswerte finden Sie unter Standardsubstitutionen verwenden.

Nächste Schritte

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