Verbindung zu Jenkins herstellen

Sie können automatische Builds mit Jenkins-Triggern und Secure Source Manager-Webhooks starten.

Erforderliche Rollen

Bitten Sie Ihren Administrator, Ihnen die folgenden IAM-Rollen zuzuweisen, um die Berechtigungen zu erhalten, die Sie zum Erstellen von Jenkins-Build-Triggern benötigen:

• Administrator von Secure Source Manager-Repositories (roles/securesourcemanager.repoAdmin) für Ihr Repository
• Auf Secure Source Manager-Instanzen zugreifende Person (roles/securesourcemanager.instanceAccessor) in der Secure Source Manager-Instanz

Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff auf Projekte, Ordner und Organisationen verwalten.

Sie können die erforderlichen Berechtigungen auch über benutzerdefinierte Rollen oder andere vordefinierte Rollen erhalten.

Informationen zum Zuweisen von Secure Source Manager-Rollen finden Sie unter Zugriffssteuerung mit IAM und Nutzern Instanzzugriff gewähren.

Webhook-Trigger einrichten

Jenkins verwendet Build-Trigger-Plug-ins, um die CI/CD-Automatisierung zu aktivieren. Sie können Trigger konfigurieren, um eingehende Ereignisse zu überwachen, z. B. wenn ein neuer Commit an ein Repository übertragen oder eine Pull-Anfrage initiiert wird, und dann automatisch einen Build ausführen, wenn neue Ereignisse eingehen. Sie können Trigger auch so konfigurieren, dass sie Code bei Änderungen am Quell-Repository oder nur bei Änderungen erstellen, die bestimmte Kriterien erfüllen.

So richten Sie einen generischen Jenkins-Webhook-Trigger ein:

1. Installieren Sie auf Ihrem Jenkins-Server das Git-Plug-in, das SSH Credential-Plug-in und das Generic Webhook Trigger-Plug-in.

2. Generieren Sie ein gültiges SSH-Schlüsselpaar auf Ihrem Jenkins-Server. Secure Source Manager unterstützt nur RSA-Schlüssel.

3. Fügen Sie die Secure Source Manager-Instanzdomain der SSH-Datei known_hosts des Jenkins-Servers hinzu, indem Sie den folgenden Befehl ausführen:

   ssh -t git@INSTANCE_ID-INSTANCE_PROJECT_NUMBER-ssh.us-central1.sourcemanager.dev
   

   Wobei:

   • INSTANCE_ID ist der Name Ihrer Secure Source Manager-Instanz.
   • INSTANCE_PROJECT_NUMBER ist die Projektnummer Ihrer Secure Source Manager-Instanz. Informationen dazu, wo Sie Ihre Projektnummer finden, finden Sie unter Projekte identifizieren.

   Mit dem folgenden Befehl wird beispielsweise die Instanzdomain für eine Instanz namens prod-test-instance mit der Projektnummer 123456789 hinzugefügt.

   ssh -t [e-mail]
   

   Antworten Sie mit yes, um die Instanzdomain der Liste der bekannten Hosts hinzuzufügen.

4. Gehen Sie in Jenkins auf die Seite Manage Credentials (Anmeldedaten verwalten):

   1. Wählen Sie SSH-Nutzername mit privatem Schlüssel aus.
   2. Fügen Sie den privaten SSH-Schlüssel Ihres Jenkins-Servers ein.
   3. Füllen Sie im Drop-down-Menü Art die anderen Felder nach Bedarf aus.

5. Klicken Sie auf Erstellen.

6. Erstellen Sie in der Jenkins-Weboberfläche einen neuen Jenkins-Job.

7. Wählen Sie auf der Konfigurationsseite des Jenkins-Jobs im Abschnitt Source Code Management (Quellcodeverwaltung) die Option Git aus.

8. Fügen Sie im Bereich Git die SSH-URL des Secure Source Manager-Repositorys als Repository-URL ein, geben Sie Ihre Build-Branches ein (z.B. */main) und wählen Sie dann die gespeicherten privaten SSH-Schlüsselanmeldedaten aus, die Sie zuvor auf der Seite Anmeldedaten verwalten hinzugefügt haben.

9. Wählen Sie im Abschnitt Build Triggers (Build-Trigger) die Option Generic Webhook Trigger (Allgemeiner Webhook-Trigger) aus.

   Optional können Sie ein Token hinzufügen, damit der Job nur ausgelöst wird, wenn dieses Token beim Aufrufen angegeben wird. Wenn Sie ein Token hinzufügen möchten, können Sie im Abschnitt Generic Webhook Trigger (Allgemeiner Webhook-Trigger) ein Token in das Feld Token eingeben.

10. Geben Sie im Abschnitt Build ein Build-Script an, das Sie für diesen Jenkins-Job verwenden möchten. Sie können beispielsweise cat README.md ausführen, um den Inhalt von README.md auszugeben.

11. Klicken Sie auf Speichern, um den Jenkins-Job zu erstellen.

Dienstkonto einrichten und erforderliche Berechtigungen erteilen

1. Wenn Sie noch kein Dienstkonto haben, das Sie verwenden möchten, erstellen Sie ein Dienstkonto.

   Prüfen Sie, ob Sie die Berechtigung iam.serviceAccounts.actAs für das Dienstkonto haben. Diese Berechtigung ist Teil der Rolle „Dienstkontonutzer“ (roles/iam.serviceAccountUser).

2. Klicken Sie in der Weboberfläche von Secure Source Manager auf das -Menü Weitere Optionen.

3. Klicken Sie auf SSH-Schlüssel für Dienstkonten. Die Seite SSH-Schlüssel für Dienstkonten wird geöffnet und eine Liste aller vorhandenen Schlüssel, die Sie hinzugefügt haben, wird angezeigt.

4. Klicken Sie auf Schlüssel hinzufügen.

5. Geben Sie auf der Seite SSH-Schlüssel hinzufügen die folgenden Werte für Ihren Schlüssel ein:

   1. Dienstkonto: Die E-Mail-Adresse des Dienstkontos, mit dem Sie den SSH-Schlüssel verwenden möchten, im Format SA_NAME@PROJECT_ID.iam.gserviceaccount.com.

      Wo

      • SA_NAME ist der Name des Dienstkontos.
      • PROJECT_ID ist die Projekt-ID des Projekts, in dem das Dienstkonto erstellt wurde.

   2. Öffentlicher SSH-Schlüssel: Ihr öffentlicher SSH-Schlüssel für Jenkins.

Berechtigungen für den Secure Source Manager-Dienst-Agent erteilen

Wenn sich das Dienstkonto nicht im selben Projekt wie Ihre Secure Source Manager-Instanz befindet, müssen Sie dem Dienst-Agent von Secure Source Manager auch die Rolle „Ersteller von Dienstkonto-Tokens“ (roles/iam.serviceAccountTokenCreator) oder die Berechtigung iam.serviceAccounts.signJwt zuweisen.

Wenn sich Ihr Dienstkonto im selben Projekt wie Ihre Secure Source Manager-Instanz befindet, fahren Sie mit Dienstkonto eine Repository-Rolle zuweisen fort.

1. Führen Sie den folgenden Befehl aus, um die vorhandene IAM-Richtlinie für Ihr Dienstkonto abzurufen:

   gcloud iam service-accounts get-iam-policy SERVICE_ACCOUNT \
       --format json
   

   Dabei ist SERVICE_ACCOUNT das Dienstkonto, das Sie verwenden möchten. Das Konto sollte entweder als numerische Dienstkonto-ID oder als E-Mail-Adresse formatiert sein, z. B. 123456789876543212345 oder [e-mail].

   Die Ausgabe enthält alle vorhandenen Bindungen oder, falls keine vorhanden sind, den Wert etag, der etwa so aussieht:

   {
   "etag": "BwUjHYKJUiQ="
   }
   

   Wichtig :Behalten Sie den etag-Wert aus der get-iam-policy-Antwort bei, damit Sie die Richtlinienänderungen einer anderen Person nicht überschreiben. Wenn Sie alle anderen Änderungen überschreiben möchten, können Sie den Wert etag entfernen.

2. Kopieren Sie die Ausgabe in eine neue Datei mit dem Namen policy.json.

3. Um dem Secure Source Manager-Dienst-Agent die Rolle „Ersteller von Dienstkonto-Tokens“ (roles/iam.ServiceAccountTokenCreator) zuzuweisen, ändern Sie policy.json so, dass Folgendes hinzugefügt wird:

   {
       "role": "roles/iam.serviceAccountTokenCreator",
       "members": [
           "serviceAccount:[e-mail]"
       ]
   }
   

   Dabei ist INSTANCE_PROJECT_NUMBER die Projektnummer Ihrer Secure Source Manager-Instanz.

4. Führen Sie den folgenden Befehl aus, um die vorhandene IAM-Richtlinie für das Dienstkonto zu ersetzen:

   gcloud iam service-accounts set-iam-policy SERVICE_ACCOUNT POLICY_FILE
   

   Ersetzen Sie Folgendes:

   • SERVICE_ACCOUNT durch die Dienstkonto-ID oder ‑E-Mail-Adresse.
   • Ersetzen Sie POLICY_FILE durch den Speicherort und den Namen der JSON-Datei mit der neuen Richtlinie.

Dienstkonto eine Repository-Rolle zuweisen

1. Rufen Sie in der Secure Source Manager-Weboberfläche das Repository auf, in dem Sie dem Dienstkonto Berechtigungen erteilen möchten.
2. Klicken Sie auf den Tab Berechtigungen.
3. Klicken Sie auf Nutzer hinzufügen.
4. Geben Sie im Feld Hauptkonto hinzufügen die E-Mail-Adresse des Dienstkontos ein.
5. Wählen Sie im Drop-down-Menü Rolle die Option Secure Source Manager Repository Reader aus.

6. Weisen Sie dem Dienstkonto die Rolle securesourcemanager.instanceAccessor mit dem folgenden Befehl zu:

   gcloud projects add-iam-policy-binding PROJECT_ID \
       --member=serviceAccount:SA_EMAIL \
       --role=roles/securesourcemanager.instanceAccessor
   

   Ersetzen Sie Folgendes:

   • PROJECT_ID durch die Projekt-ID der Secure Source Manager-Instanz.
   • SA_EMAIL durch die E-Mail-Adresse des Dienstkontos.

Webhook einrichten

1. Rufen Sie in der Secure Source Manager-Weboberfläche das Repository auf, für das Sie einen Webhook erstellen möchten.
2. Klicken Sie auf Einstellungen.
3. Klicken Sie auf Webhooks und dann auf Webhook hinzufügen.

4. Geben Sie im Feld Hook-ID eine ID für den Webhook ein.

   Hinweis :Hook-IDs müssen der Namenskonvention für Ressourcen entsprechen. Sie dürfen nur Kleinbuchstaben, Ziffern oder Bindestriche enthalten, müssen mit einem Buchstaben beginnen und können nach dem Erstellen des Webhooks nicht mehr geändert werden.

5. Geben Sie im Feld Target URL (Ziel-URL) die Jenkins-Trigger-URL ein.

6. Wenn Sie das optionale Token beim Konfigurieren des Jenkins-Triggers verwendet haben, enthält die Jenkins-Trigger-URL dieses Token am Ende. Um zu verhindern, dass das Token preisgegeben wird, entfernen Sie es vom Ende der Ziel-URL und kopieren Sie es in das Feld Sensibler Abfragestring.

   Suchen Sie in der Trigger-URL nach dem Text, der mit token= beginnt, um das Token zu finden.

   Wenn Ihre URL beispielsweise so aussieht: https://jenkins-server.com/generic-webhook-trigger/invoke?token=jenkins-job1

   Kopieren Sie den Teil ab dem Fragezeichen ?token=jenkins-job1 und entfernen Sie ihn aus dem Feld Ziel-URL. Entfernen Sie dann das ursprüngliche Fragezeichen und verschieben Sie den verbleibenden Teil token=jenkins-job1 in das Feld Sensibler Abfragestring.

7. Wählen Sie im Bereich Auslösen bei eine der folgenden Optionen aus:

   • Push: wird ausgelöst, wenn ein Push an das Repository erfolgt.
   • Pull-Anfrage-Status geändert: Wird ausgelöst, wenn sich der Status der Pull-Anfrage ändert.

8. Wenn Sie Push ausgewählt haben, können Sie im Feld Branch-Filter eine Zulassungsliste für Push-Ereignisse eingeben.

   Im Feld Branch filter wird das Glob-Muster verwendet. Nur Vorgänge in den übereinstimmenden Branches lösen einen Build aus. Wenn das Feld leer oder * ist, werden Push-Ereignisse für alle Zweige gemeldet.

9. Klicken Sie auf Add webhook (Webhook hinzufügen).

10. Der Webhook wird auf der Seite Webhooks angezeigt.

    Hinweis :Wenn Sie einen Webhook hinzufügen oder bearbeiten, kann die Länge von Sensitive Query String von der eingegebenen Länge abweichen. Das ist normal, da Platzhalterstrings verwendet werden, um die Sicherheit zu gewährleisten.

Webhook testen

1. Klicken Sie in Secure Source Manager auf der Seite Webhooks auf den Webhook, den Sie testen möchten.

2. Klicken Sie unten auf der Seite auf Zustellung testen.

   Der Zustellwarteschlange wird ein gefälschtes Ereignis hinzugefügt. Es kann einige Sekunden dauern, bis sie im Zustellungsverlauf angezeigt wird.

3. Sie können auch einen git-Befehl verwenden, um einen Pull-Request zu pushen oder zusammenzuführen und den Webhook zu testen.

4. Sehen Sie sich im Jenkins-Projekt den Build an, der durch das Testereignis ausgelöst wurde. Sie finden ihn im Build-Verlauf.

5. Nachdem Sie Ihre erste Testlieferung gesendet haben, können Sie sich auch die Anfrage und Antwort für die Testlieferung im Bereich Letzte Lieferungen auf der Seite für Secure Source Manager-Webhooks ansehen.

Nächste Schritte

• Jenkins-Dokumentation