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.

Geltungsbereich

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.

Hinweis: Wenn Sie Repositories nach Cloud Source Repositories spiegeln, wird die E-Mail-Adresse in Pub/Sub-Benachrichtigungen immer als [e-mail] angezeigt.

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": "[e-mail]",
      "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.