Repositories aus Bitbucket Cloud erstellen

Auf dieser Seite wird erläutert, wie Sie mithilfe von Webhook-Triggern Bitbucket Cloud nutzen können.

Hinweis

Cloud Build and Secret Manager APIs aktivieren.
Aktivieren Sie die APIs

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

Hinweis: Wenn Sie die gcloud CLI bereits installiert haben, führen Sie gcloud components update aus, damit Sie die neueste verfügbare Version haben.

Einrichten

Bevor Sie einen Webhook-Trigger erstellen, um Bitbucket Cloud zu nutzen, müssen Sie einen SSH-Schlüssel erstellen, um Ihre Verbindung zu Bitbucket Cloud zu authentifizieren. Wenn Sie einen Trigger ohne ein zugeordnetes Repository erstellen und auf einen Code in einem externen Quellcode-Verwaltungssystem wie Bitbucket Cloud zugreifen, müssen Sie Ihren SSH-Schlüssel in Ihrer Inline-Build-Konfiguration abrufen.

In diesem Abschnitt wird erläutert, wie Sie Ihren SSH-Schlüssel sowohl erstellen als auch speichern können, bevor Sie einen Webhook-Trigger erstellen.

SSH-Schlüssel erstellen

Für den Zugriff auf den Code auf Bitbucket Cloud müssen Sie einen SSH-Schlüssel in Ihrer Inline-Build-Konfiguration abrufen.

So erstellen Sie einen SSH-Schlüssel:

Öffnen Sie ein Terminalfenster.
Erstellen Sie ein neues Verzeichnis mit dem Namen working-dir und rufen Sie dieses Verzeichnis auf:
```
mkdir working-dir
cd working-dir
```
Erstellen Sie einen neuen Cloud-SSH-Schlüssel für Bitbucket. Dabei ist bitbucket.org die URL für Ihr Bitbucket Cloud-Repository:
```
ssh-keygen -t rsa -b 4096 -N '' -C bitbucket.org -f id_bitbucket
```
Der Befehl erstellt unter working-dir/id_bitbucket einen neuen SSH-Schlüssel ohne Passphrase für Ihren SSH-Schlüssel. Cloud Build kann Ihren SSH-Schlüssel nicht verwenden, wenn er mit einer Passphrase geschützt ist.

Öffentlichen SSH-Zugriffsschlüssel auf Bitbucket Cloud hinzufügen

Um Operationen zu sichern, die andere Systeme auf Ihren in Bitbucket Cloud verwalteten Repositories durchführen, müssen Sie Ihren öffentlichen SSH-Zugangsschlüssel auf Bitbucket Cloud hinzufügen und Ihrem Schlüssel Leserechte gewähren. Informationen zum Hinzufügen Ihres Schlüssels finden Sie unter Zugriffsschlüssel hinzufügen.

Anmeldedaten in Secret Manager erstellen und speichern

Wenn Sie einen SSH-Schlüssel erstellen, wird in Ihrer lokalen Umgebung die id_bitbucket-Datei erzeugt. Da diese Datei sensible Informationen im Zusammenhang mit der Authentifizierung enthält, müssen Sie sie im Secret Manager speichern, bevor Sie sie zum Aufrufen eines Builds verwenden.

Zusätzlich zum Secret, das beim Erstellen eines Webhook-Triggers verwendet wird, müssen Sie in Secret Manager ein Secret erstellen, um eingehende Webhook-Ereignisse in Cloud Build zu validieren und zu autorisieren.

So erstellen und speichern Sie Ihre Anmeldedaten im Secret Manager:

Rufen Sie in der Google Cloud Console die Seite „Secret Manager“ auf:

Zur Seite „Secret Manager“
Klicken Sie auf der Seite Secret Manager auf Secret erstellen.
Geben Sie auf der Seite Secret erstellen unter Name einen Namen für Ihr Secret ein.
Geben Sie im Feld Secret-Wert einen Namen für Ihr Secret ein oder laden Sie eine Datei hoch.

Klicken Sie zum Hochladen der SSH-Schlüsseldatei auf Hochladen und fügen Sie die Datei working-dir/id_bitbucket ein.
Lassen Sie den Abschnitt Regionen unverändert.
Klicken Sie auf Secret erstellen, um Ihr Secret zu erstellen.

Nachdem Sie das Secret erstellt haben, gewährt die Google Cloud Console Ihrem Cloud Build-Dienstkonto ${PROJECT_NUMBER}@gcp-sa-cloudbuild.iam.gserviceaccount.com automatisch die Rolle Zugriffsfunktion für Secret Manager-Secret. Wenn diese Rolle in Ihrem Dienstkonto nicht angezeigt wird, führen Sie die folgenden Schritte aus, die unter Rolle Secret Manager Ihrem Dienstkonto zuweisen beschrieben werden.

Nachdem Sie den SSH-Schlüssel gespeichert haben, können Sie ihn auch aus der Umgebung löschen. Führen Sie dazu den folgenden Befehl aus:

rm id_bitbucket*

Sie können jetzt Ihren Webhook-Trigger erstellen.

Webhook-Trigger erstellen

Console

So erstellen Sie einen Webhook-Trigger, der Builds aus der Bitbucket Cloud über die Google Cloud Console aufruft:

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 Sie global als Region auswählen, verwendet Cloud Build den Standardpool zum Ausführen des Builds.
  - Wenn Sie eine nicht globale Region auswählen und die mit dem Trigger verknüpfte Build-Konfigurationsdatei einen privaten Pool angibt, verwendet Cloud Build den privaten Pool, um den 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 Sie eine nicht globale Region auswählen und die mit dem Trigger verknüpfte Build-Konfigurationsdatei keinen privaten Pool angibt, 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.
  - 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 Ihrem SSH-Schlüssel zugeordnet ist.
    
    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 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.
  
  Wenn Sie global als Region ausgewählt haben, rufen Sie mit dem folgenden Befehl ein Webhook-Ereignis auf:
```
curl -X POST -H "application/json" "https://cloudbuild.googleapis.com/v1/projects/${PROJECT_ID}/triggers/${TRIGGER_NAME}:webhook?key=${API_KEY}&secret=${SECRET_VALUE}" -d "{}"
```
  Wenn Sie eine nicht globale Region wie us-central1 auswählen, rufen Sie mit dem folgenden Befehl ein Webhook-Ereignis auf:
```
curl -X POST -H "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 "{}"
```
  Wie Sie die URL beim Erstellen eines Webhooks in Bitbucket Cloud verwenden können erfahren Sie unter Webhook in Bitbucket Cloud erstellen.
- Quelle (optional): Das Repository, das beim Ausführen des Webhook-Triggers erstellt werden soll. Lassen Sie dieses Feld leer. In diesem Beispiel ist die Build-Konfiguration eine Inline-Build-Konfiguration, sodass keine Quelle erforderlich ist.
- Konfiguration: Erstellen Sie eine Inline-Build-Konfiguration in der Google Cloud Console.
  
  Im folgenden Beispiel authentifiziert die Inline-Build-Konfiguration Ihre Verbindung zu Bitbucket Cloud mithilfe Ihres SSH-Schlüssels und greift auf Ihr angegebenes Repository zu. Danach wird das Commit geprüft, das den Webhook aufgerufen hat.
```
steps:
# first, setup SSH:
# 1- save the SSH key from Secret Manager to a file
# 2- add the host key to the known_hosts file
- name: gcr.io/cloud-builders/git
  args:
    - '-c'
    - |
      echo "$$SSHKEY" > /root/.ssh/id_rsa
      chmod 400 /root/.ssh/id_rsa
      ssh-keyscan bitbucket.org > /root/.ssh/known_hosts
  entrypoint: bash
  secretEnv:
    - SSHKEY
  volumes:
    - name: ssh
      path: /root/.ssh
# second, clone the repository
- name: gcr.io/cloud-builders/git
  args:
    - clone
    - '-n'
    - 'git@bitbucket.org/BITBUCKET_REPO'
    - .
  volumes:
    - name: ssh
      path: /root/.ssh
# third, checkout the specific commit that invoked this build
- name: gcr.io/cloud-builders/git
  args:
    - checkout
    - $_TO_SHA
availableSecrets:
  secretManager:
  - versionName: PATH_TO_SECRET_VERSION
    env: SSHKEY
```
  Wobei:
  - BITBUCKET_REPO ist der Pfad für Ihr Bitbucket-Repository.
  - PATH_TO_SECRET_VERSION ist der Pfad zu Ihrer Secret-Version, wie sie in Secret Manager gespeichert ist. Dies ist das Secret, das Ihren SSH-Schlüssel enthält. Beispiel: projects/project-id/secrets/secret-name/versions/1
  - SSHKEY ist der Name der Umgebungsvariablen, die in diesem Fall zum Speichern des Pfads zu Ihrem Secret verwendet wird.
- Substitutionen (optional): Sie können mit diesem Feld Trigger-spezifische Substitutionsvariablen definieren.
  
  Angenommen, Sie möchten nach einem bestimmten Zweignamen suchen, der mit einer Commit-ID verknüpft ist, und dann in der Build-Definition zu diesem Zweignamen wechseln. Zum Abrufen dieser Daten können Sie Substitutionsvariablen mit Nutzlastbindungen erstellen, um den Zweignamen zu speichern.
  
  Geben Sie unten die folgenden Variablen und Werte an:
  
  Variablenname Variablenwert:
  
  _BRANCH $(body.push.changes[0].new.name)
  
  _TO_SHA $(body.push.changes[0].new.target.hash)
  
  Informationen zu den mit Bitbucket Cloud-Ereignissen verknüpften Nutzlasten finden Sie unter Ereignisnutzlasten.
- 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.
  
  Da der Trigger einen Build ausführen soll, wenn der Zweigname mit main übereinstimmt, können Sie den Operator "==" verwenden, um nach genauen Übereinstimmungen zu suchen. Sie können auch das Keyword "matches" verwenden, wenn Sie nach regulären Ausdrücken suchen möchten.
  
  Geben Sie Folgendes als Filter an:
  - _BRANCH == refs/heads/main
  Weitere Beispiele für Filtersyntaxen, die Sie auf Ihre Webhook-Trigger anwenden können, finden Sie unter CEL zum Filtern von Build-Ereignissen verwenden.
Klicken Sie auf Erstellen, um den Build-Trigger zu erstellen.

Variablenname	Variablenwert:
`_BRANCH`	`$(body.push.changes[0].new.name)`
`_TO_SHA`	`$(body.push.changes[0].new.target.hash)`

gcloud

So erstellen Sie einen Webhook-Trigger, der Builds aus Bitbucket Cloud aufruft:

     gcloud alpha builds triggers create webhook \
       --name=TRIGGER_NAME \
       --secret=PATH_TO_SECRET \
       --substitutions='' \
       --filter='' \
       --inline-config=PATH_TO_INLINE_BUILD_CONFIG \ # or --repo=PATH_TO_REPO
       --branch=BRANCH_NAME #  or --tag=TAG_NAME

Wobei:

TRIGGER_NAME ist der Name des Triggers.
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-Konfiguration. Die Build-Konfiguration wird zwar inline auf dem von Ihnen erstellten Trigger gespeichert, der Konfigurationspfad wird jedoch aus einer lokalen Datei abgerufen.
PATH_TO_REPO ist der Pfad zum Repository, für das ein Build aufgerufen werden soll. Beispiel: https://bitbucket.org/username/repo-slug. Die Repository-URL sollte ein mit Cloud Build verbundenes Repository sein.

Hinweis: Sie können das Flag --inline-config oder --repo angeben. Die Flags schließen sich gegenseitig aus. Beide Flags müssen nicht angegeben werden.
BRANCH_NAME ist der Name Ihres Zweigs, wenn Sie den Trigger auf einem Zweig erstellen möchten.
TAG_NAME ist der Name Ihres Tags, wenn Sie den Trigger auf einem Tag aufbauen möchten.

Webhook in Bitbucket Cloud erstellen

Damit Bitbucket Cloud Anfragen an Cloud Build senden kann, müssen Sie einen Webhook in Bitbucket Cloud erstellen. Folgen Sie dazu der Anleitung unter Webhook erstellen und auslösen.

Jetzt wird jedes Mal, wenn Aktualisierungen in Ihrem Repository dem Trigger-Ereignis entsprechen, das Sie in Ihrem Webhook angegeben haben, automatisch ein Build von Cloud Build-Webhook-Triggern aufgerufen.