Benachrichtigungen für Cloud Source Repositories

Cloud Source Repositories veröffentlicht Nachrichten zu Ihrem Repository in benannten Ressourcen, die als Themen bezeichnet werden. Anwendungen, die Pub/Sub-Themen abonniert haben, können diese Nachrichten empfangen. Wenn sich beispielsweise Ihr Repository-Status ändert, können Sie eine Benachrichtigung erhalten. Darüber hinaus können Sie Rollen und Berechtigungen für Ihre Pub/Sub-Themen konfigurieren, um zu steuern, wie Nutzer mit Pub/Sub-Ereignissen interagieren, die von Ihrem Repository generiert werden.

Diese Seite bietet einen Überblick über Pub/Sub-Benachrichtigungen für Cloud Source Repositories. Informationen zum Einrichten und Verwenden von Pub/Sub-Benachrichtigungen finden Sie unter Pub/Sub-Benachrichtigungen konfigurieren.

Umfang

Sie können Cloud Source Repositories so konfigurieren, dass Ereignisse in einem Pub/Sub-Thema veröffentlicht werden. Sie können den Umfang dieser Konfiguration als gesamtes Google Cloud-Projekt oder als einzelnes Repository festlegen.

Nach der Konfiguration veröffentlicht Cloud Source Repositories mithilfe Ihres Dienstkontos Nachrichten an das angegebene Pub/Sub-Thema. Sie müssen dem Dienstkonto zuerst die Berechtigungen zum Veröffentlichen des Themas erteilen. Wenn Sie Audit-Logging für Pub/Sub aktiviert haben, wird dieses Dienstkonto als Aufrufer der Pub/Sub-APIs angezeigt.

Berechtigungen

Zum Konfigurieren von Cloud Source Repositories zum Veröffentlichen von Nachrichten ist Folgendes erforderlich:

  • Ein Projekt oder ein Repository, das nach Ereignissen überwacht wird. Wenn ein Projekt angegeben ist, werden alle Repositories unter diesem Projekt überwacht.
  • Ein Pub/Sub-Thema, an das Cloud Source Repositories Nachrichten veröffentlicht.
  • Ein Dienstkonto für den Zugriff auf das Pub/Sub-Thema.
  • Ein Nachrichtenformat wie JSON oder Protocol Buffers.

Wenn Sie Cloud Source Repositories für Pub/Sub konfigurieren, benötigen Sie folgende Berechtigungen:

  • source.repos.updateRepo für das angegebene Repository oder source.repos.updateProjectConfig für das angegebene Projekt
  • iam.serviceAccounts.actAs für das angegebene Dienstkonto

Nachdem das Pub/Sub-Thema registriert wurde, muss das angegebene Dienstkonto pubsub.topics.publish-Berechtigungen haben, um eine Nachricht zu veröffentlichen.

Ereignistypen

Pub/Sub kann Sie benachrichtigen, wenn ein Nutzer ein Repository erstellt, ein Repository löscht oder ein Commit an ein Repository sendet. Jedes Ereignis ist ein bestimmter Ereignistyp. In der folgenden Tabelle sind die Typen und die zugehörigen Definitionen aufgeführt.

Ereignistyp Beschreibung
CreateRepo Tritt auf, wenn ein Nutzer ein Repository erstellt.
RefUpdate Tritt auf, wenn ein Nutzer einen Git-Push-Befehl ausführt.
DeleteRepo Tritt auf, wenn ein Nutzer ein Repository löscht.

Benachrichtigungsformat

Sie können Pub/Sub so konfigurieren, dass eines der beiden folgenden Formate für Benachrichtigungen verwendet wird:

  • JSON
  • Protocol Buffers

Benachrichtigungsdaten

Jede Pub/Sub-Benachrichtigung enthält die folgenden Informationen zu einem Ereignis:

Feldname Beschreibung
Name Name des Repositorys.
url URL des Repositorys.
eventTime Zeit, zu der die Änderung erfolgt ist.
refUpdateEvent Informationen über die spezifische Änderung.
createRepoEvent Gibt an, ob ein Nutzer ein Repository erstellt hat.
deleteRepoEvent Gibt an, ob ein Nutzer ein Repository gelöscht hat.

Wenn die Benachrichtigung einen git push-Befehl betrifft, enthält die Benachrichtigung mit dem Feld refUpdateEvent die folgenden Informationen:

Feldname Beschreibung
email E-Mail-Adresse des Nutzers, der die Änderung vorgenommen hat.
refUpdates Informationen zum Commit.

Das Feld refUpdates enthält die folgenden Details zum Befehl git push:

Feldname Beschreibung
refName Name des Branch.
updateType Art der Aktualisierung. Weitere Informationen finden Sie unter Aktualisierungstypen.
oldId Vorherige Commit-ID für das Repository.
newId Neue ID für das Repository.

Aktualisierungstypen

Ein git push-Ereignis kann einen von vier Aktualisierungstypen haben. Sie finden den Typ im Feld updateType der Benachrichtigung.

Art der Aktualisierung Beschreibung
CREATE Tritt auf, wenn der Befehl eine neue Referenz erstellt.
UPDATE_FAST_FORWARD Tritt auf, wenn der Befehl ein Objekt aktualisiert.
UPDATE_NON_FAST_FORWARD Tritt auf, wenn der Befehl das Flag -f verwendet, z. B. git push -f.
DELETE Tritt auf, wenn der Befehl eine Referenz löscht.

Benachrichtigungsbeispiel

Im Folgenden finden Sie ein Beispiel für die Daten, die in einer Pub/Sub-Benachrichtigung enthalten sind. Diese Benachrichtigung liegt im JSON-Format vor.

  {
    "name": "projects/test-project/repos/pubsub-test",
    "url": "[URL_PATH]",
    "eventTime": "2018-02-21T21:23:25.566175Z",
    "refUpdateEvent": {
      "email": "someone@somecompany.com",
      "refUpdates": {
        "refs/heads/master": {
          "refName": "refs/heads/master",
          "updateType": "UPDATE_FAST_FORWARD",
          "oldId": "c7a28dd5de3403cc384a025834c9fce2886fe763",
          "newId": "f00768887da8de62061210295914a0a8a2a38226"
        }
      }
    }
  }

Beispiel für die projektübergreifende Einrichtung

Sie können Cloud Source Repositories so konfigurieren, dass eine Nachricht an ein Thema in einem anderen Projekt veröffentlicht wird. In diesem Fall müssen Sie ein Dienstkonto in demselben Projekt erstellen, in dem sich Ihr Repository befindet. Geben Sie in dem Projekt, das das Pub/Sub-Thema enthält, diesem Dienstkonto die Rolle roles/pubsub.publisher. Wenn Sie Cloud Source Repositories mit diesem Konto und diesem Pub/Sub-Thema konfigurieren, werden die Ereignisnachrichten für Ihr Repository im Thema des anderen Projekts angezeigt.