Google verwendet KI-Technologie, um Inhalte in Ihre bevorzugte Sprache zu übersetzen. KI-Übersetzungen können Fehler enthalten.

Builds als Reaktion auf Webhook-Ereignisse automatisieren

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

Bei Webhook-Triggern können Sie eine Inline-Build-Konfiguration anstelle eines Quell-Repositorys angeben. Mit dieser Inline-Konfiguration haben Sie die Kontrolle über Git-Vorgänge und den Build-Workflow. Wenn Sie stattdessen Builds bei Repository-Ereignissen automatisieren möchten, können Sie Cloud Build-Repository-Trigger verwenden, die sich direkt in Anbieter wie GitHub und GitLab einbinden lassen.

Mit Webhook-Triggern können Sie eine Inline-Build-Konfigurationsdatei definieren, anstatt beim Erstellen des Triggers eine Quelle anzugeben. Mit der Inline-Build-Konfiguration haben Sie die Kontrolle über Git-Vorgänge und können 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

Aktivieren Sie die Cloud Build API und die Secret Manager API, falls sie noch nicht aktiviert sind.
Erforderliche Rollen zum Aktivieren von APIs
Zum Aktivieren von APIs benötigen Sie die Berechtigung serviceusage.services.enable. Wenn Sie das Projekt erstellt haben, haben Sie diese Berechtigung wahrscheinlich bereits über die Inhaberrolle (roles/owner). Andernfalls können Sie diese Berechtigung über die Rolle „Service Usage-Administrator“ (roles/serviceusage.serviceUsageAdmin) erhalten. Informationen zum Zuweisen von Rollen
APIs aktivieren

Wenn Sie die gcloud-Befehle auf dieser Seite 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.
Wenn Ihr Webhook-Trigger ein Cloud Build-Repository als Quelle verwendet, sollten Sie sich mit Cloud Build-Repositories vertraut machen.

Webhook-Trigger erstellen

Console

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

Seite "Trigger" aufrufen

Zur Seite "Build-Trigger"
Wählen Sie das Projekt oben auf der Seite aus und klicken Sie auf Öffnen.
Klicken Sie auf Trigger erstellen.
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 mit dem Trigger verknüpften Build-Konfigurationsdatei ein privater Pool angegeben ist, verwendet Cloud Build den privaten Pool, um Ihren Build auszuführen. In diesem Fall muss die im Trigger angegebene Region mit der Region übereinstimmen, in der Sie den privaten Pool erstellt haben.
  - Wenn in der mit dem Trigger verknüpften Build-Konfigurationsdatei kein privater Pool angegeben ist, verwendet Cloud Build den Standardpool, um den Build in derselben Region wie den Trigger auszuführen.
- 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. Sie benötigen einen Secret, um eingehende Webhook-Ereignisse zu authentifizieren. Sie können ein neues Secret erstellen oder ein vorhandenes verwenden. Dieses Secret ist unabhängig von dem Secret, das mit Ihrem SSH-Schlüssel verknüpft ist.
  
  So erstellen Sie ein Secret:
  1. Wählen Sie Neues Secret verwenden (von Cloud Build generiert) aus.
  2. Klicken Sie auf Secret erstellen.
    
    Das Dialogfeld 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 Secret Manager-Rolle für Ihr Dienstkonto zuweisen.
    
    Nachdem Sie das Secret erstellt oder ausgewählt haben, wird eine Vorschau der Webhook-URL angezeigt. Ihre URL enthält einen von Cloud Build und Ihrem Secret generierten API-Schlüssel. Wenn Cloud Build Ihren API-Schlüssel nicht abrufen kann, können Sie ihn manuell zur URL hinzufügen oder einen API-Schlüssel abrufen, falls Sie noch keinen haben.
    
    Sie können die URL verwenden, um ein Webhook-Ereignis aufzurufen, indem Sie eine HTTP-Anfrage mit der POST-Methode senden.
    
    Nachdem Sie diese Schritte ausgeführt haben, wird Ihrem Cloud Build-Dienst-Agent service-${PROJECT_NUMBER}@gcp-sa-cloudbuild.iam.gserviceaccount.com automatisch die Rolle Secret Manager Secret Accessor zugewiesen. Wenn diese Rolle nicht automatisch zu Ihrem Dienst-Agent hinzugefügt wird, führen Sie die Schritte unter Secret Manager-Rolle dem Dienstkonto zuweisen aus.
- Quelle (optional): Wenn Sie eine Inline-Build-Konfiguration angeben, müssen Sie keine Quelle angeben. Gehen Sie andernfalls so vor:
  - Repository-Generation: Wählen Sie 2. Generationaus.
  - Repository: Wählen Sie aus der Liste der verfügbaren Repositories das Repository aus, aus dem Sie erstellen möchten. Die Region Ihres Repositorys muss mit der Region Ihres Triggers übereinstimmen.
  - 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 als Ereignis ausgewählt haben, wählen Sie eine der folgenden Optionen aus, um festzulegen, ob der Trigger automatisch einen Build aufruft:
    
    Warnung: Jeder Nutzer mit Lesezugriff auf das Repository kann eine Pull-Anfrage senden, die möglicherweise einen Build ausführt, der Änderungen am Quellcode aus der Pull-Anfrage enthält. 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-Zeit-Berechtigungen von Triggern
    - Erforderlich außer für Inhaber und Mitbearbeiter: Wenn ein Pull-Request von einem Repository-Inhaber oder -Mitbearbeiter erstellt oder aktualisiert wird, werden Builds automatisch ausgeführt. Wenn ein externer Mitwirkender die Aktion initiiert, werden Builds erst ausgeführt, nachdem ein Owner oder Mitbearbeiter den Pull-Anfrage mit /gcbrun kommentiert hat.
    - Erforderlich: Wenn eine Pull-Anfrage von einem Mitwirkenden erstellt oder aktualisiert wird, werden Builds erst ausgeführt, nachdem ein Inhaber oder Mitbearbeiter die Pull-Anfrage mit /gcbrun kommentiert hat. Builds werden jedes Mal ausgeführt, wenn eine Änderung an einer Pull-Anfrage vorgenommen wird.
    - Nicht erforderlich: Wenn eine Pull-Anfrage von einem Mitwirkenden erstellt oder aktualisiert wird, werden Builds automatisch 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 als Konfigurationsoption eine Inline-Build-Konfigurationsdatei 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, des Verzeichnisses Dockerfile oder des Buildpacks-Verzeichnisses 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 Dockerfile- oder Buildpack-Image-Namen angegeben haben, wird eine Vorschau des docker build- oder pack-Befehls angezeigt, der für den Build ausgeführt 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 die Build-Konfigurationsdatei in derGoogle Cloud Console mit 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 innerhalb eines Triggers eine Regel erstellen, die festlegt, ob der Trigger einen Build auf Basis der Substitutionsvariablen ausführt.
Klicken Sie auf Erstellen, um den Build-Trigger zu erstellen.

gcloud

So erstellen Sie einen Webhook-Trigger:

gcloud builds triggers create webhook \
  --trigger-config=TRIGGER_CONFIG_PATH \
  --name=TRIGGER_NAME \
  --description=DESCRIPTION \
  --region=REGION \
  --secret=projects/PROJECT_ID/secrets/SECRET_NAME/versions/SECRET_VERSION \
  --service-account=SERVICE_ACCOUNT \ 
  --repository=projects/PROJECT_ID/locations/REGION/connections/CONNECTION_NAME/repositories/REPO_NAME \ 
  --build-config=PATH_TO_BUILD_CONFIG \
  --inline-config=PATH_TO_INLINE_BUILD_CONFIG \
  --dockerfile=DOCKERFILE \
  --dockerfile-dir=DOCKERFILE_DIR \
  --dockerfile-image=DOCKERFILE_IMAGE \
  --tag=TAG_NAME \
  --branch=BRANCH_NAME \
  --substitutions=_SUB_ONE=SUBSTITUTION \
  --subscription-filter=FILTER \
  --require-approval

Wobei:

TRIGGER_CONFIG_PATH ist der Pfad zu einer Trigger-Konfigurationsdatei. Wenn Sie eine Trigger-Konfigurationsdatei verwenden, müssen die Felder name, description, region, secret, service-account, subscription-filter und substitution undefiniert bleiben. Weitere Informationen finden Sie in der Cloud Build-Referenzdokumentation unter BuildTrigger.
TRIGGER_NAME ist der Name des Triggers.
DESCRIPTION (Optional) ist eine Beschreibung für den Trigger.
REGION ist die Region für Ihren Trigger. Dieser Wert muss eine andere Region als „global“ sein.
SECRET_NAME ist der Name Ihres Secrets, wie es in Secret Manager gespeichert ist.
SECRET_VERSION ist die Version, die mit Ihrem Secret verknüpft ist, wie es in Secret Manager gespeichert ist.
SERVICE_ACCOUNT ist das Dienstkonto, das zum Ausführen aller nutzergesteuerten Vorgänge im Zusammenhang mit Ihrem Build-Trigger verwendet wird. Wenn Sie kein Dienstkonto definieren, verwendet Cloud Build das Standarddienstkonto für Cloud Build.
PROJECT_ID ist Ihre Google Cloud Projekt-ID.
CONNECTION_NAME ist der Name Ihrer Hostverbindung.
REPO_NAME ist der Name Ihres Repositorys.
PATH_TO_BUILD_CONFIG ist der Pfad zu einer Build-Konfigurationsdatei. Verwenden Sie diesen Parameter, wenn sich Ihr Trigger auf eine Build-Konfigurationsdatei in einem Cloud Build-Repository bezieht. Wenn Sie diesen Parameter festlegen, können Sie keinen inline-config definieren oder Parameter für ein Dockerfile verwenden.
PATH_TO_INLINE_BUILD_CONFIG ist der Pfad zu einer Inline-Build-Konfiguration. Verwenden Sie diesen Parameter, wenn sich der Trigger auf eine lokale Build-Konfigurationsdatei bezieht. Wenn Sie diesen Parameter festlegen, können Sie keinen build-config definieren oder Parameter für ein Dockerfile verwenden.
DOCKERFILE ist der Pfad zu einem Dockerfile. Verwenden Sie diesen Parameter, wenn sich Ihr Trigger auf ein Dockerfile bezieht. Wenn Sie Dockerfile-Parameter festlegen, können Sie keinen build-config oder inline-config definieren.
DOCKERFILE_DIR ist das Verzeichnis des Dockerfile.
DOCKERFILE_IMAGE ist der Name des Docker-Images, das von Cloud Build erstellt wird.
BRANCH_NAME ist der Name Ihres Zweigs, wenn Sie den Trigger so einrichten möchten, dass er auf einem Zweig erstellt wird. Wenn Sie diesen Parameter festlegen, können Sie keinen tag definieren.
TAG_NAME ist der Name des Tags, wenn Sie den Trigger so einrichten möchten, dass er auf einem Tag basiert. Wenn Sie diesen Parameter festlegen, können Sie keinen branch definieren.
SUBSTITUTION (optional) sind Parameter, die in der Build-Spezifikation ersetzt werden sollen. Beispiel: _SUB_ONE='$(body.message.test)',_SUB_TWO='$(body.message.output)'
FILTER (optional) ist ein CEL-Filterausdruck für den Trigger, z. B. '_SUB_ONE == "prod"'.
(Optional) Wenn --require-approval im Befehl vorhanden ist, erfordert Cloud Build eine manuelle Genehmigung für ausgelöste Builds.

Webhook-Ereignis aufrufen

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 "{}"

(Optional) Secret Manager-Rolle für Ihr Dienstkonto gewähren

Wenn Sie Ihr Secret während der Erstellung des Webhook-Triggers konfigurieren, weist Cloud Build in den meisten Fällen automatisch die Rolle Secret Manager Secret Accessor Dienstkonten zu, die die Rolle benötigen. Wenn Sie jedoch ein vorhandenes Secret verwenden, müssen Sie Ihrem Cloud Build-Dienstkonto möglicherweise auch manuell die Rolle „Secret Manager Secret Accessor“ zuweisen:

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

Seite "IAM" öffnen
Optional: Wenn Sie von Google bereitgestellte Konten sehen möchten, klicken Sie auf das Kästchen Von Google bereitgestellte Rollenzuweisungen einschließen.
Notieren Sie sich das Build-Dienstkonto, dem Sie die Rolle zuweisen möchten.
Öffnen Sie in der Google Cloud Console die Seite Secret Manager:

Zur Seite "Secret Manager"
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 erlauben.
  
  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 > Secret Manager Secret Accessor aus.
5. Klicken Sie auf Speichern.

(Optional) API-Schlüssel abrufen

Sie benötigen einen API-Schlüssel, um ein eingehendes Webhook-Ereignis zu authentifizieren. Dieser API-Schlüssel ist Teil des Secrets, das Sie beim Konfigurieren des Webhook-Triggers auswählen. Wenn Sie noch keinen API-Schlüssel haben oder Cloud Build beim Konfigurieren Ihres Secrets in der Google Cloud Console keinen abrufen konnte, können Sie manuell einen API-Schlüssel erstellen:

So erhalten Sie einen API-Schlüssel:

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

Öffnen Sie die Seite Anmeldedaten
Klicken Sie auf Anmeldedaten erstellen.
Klicken Sie auf API-Schlüssel.

Es wird ein Dialogfeld mit Ihrem erstellten API-Schlüssel angezeigt. Notieren Sie sich Ihren API-Schlüssel.
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.