Cloud Source Repositories の通知

Cloud Source Repositories は、リポジトリに関するメッセージを、トピックと呼ばれる名前付きリソースに公開します。Pub/Sub トピックに登録されたアプリは、これらのメッセージを受信できます。たとえば、リポジトリの状態が変更されたときにアラートを受信できます。また、リポジトリが生成する Pub/Sub イベントの操作を制御するため、Pub/Sub サブトピックの役割と権限を構成できます。

このページでは、Cloud Source Repositories の Pub/Sub 通知の概要について説明します。Pub Sub 通知の設定と使い方については、Pub/Sub 通知を構成するをご覧ください。

スコープ

Pub/Sub トピックにイベントを公開するように、Cloud Source Repositories を構成できます。この構成のスコープは、Google Cloud プロジェクト全体にすることも、個々のリポジトリにすることもできます。

構成後、Cloud Source Repositories はサービス アカウントを使用して特定の Pub/Sub トピックにメッセージを公開します。まず、トピックへの公開権限をサービス アカウントに付与する必要があります。Pub/Sub に監査ロギングを有効にしている場合、このサービス アカウントが Pub/Sub API の呼び出し側として表示されます。

権限

メッセージを公開するように Cloud Source Repositories を構成するには、次のものが必要です。

  • イベントを監視するプロジェクトまたはリポジトリ。プロジェクトが指定されている場合、そのプロジェクトのリポジトリはすべて監視されます。
  • Cloud Source Repositories がメッセージを公開する Pub/Sub トピック。
  • Pub/Sub トピックにアクセスするサービス アカウント。
  • メッセージの形式(JSON、プロトコル バッファなど)。

Pub/Sub の Cloud Source Repositories を構成するには、次の権限が必要です。

  • 指定されたリポジトリに対する source.repos.updateRepo または指定されたプロジェクトに対する source.repos.updateProjectConfig
  • 指定されたサービス アカウントに対する iam.serviceAccounts.actAs

Pub/Sub トピックを登録した後、メッセージを公開するには、指定したサービス アカウントに pubsub.topics.publish 権限が必要です。

イベントタイプ

ユーザーがリポジトリの作成、リポジトリの削除またはリポジトリへの commit の push を行ったときに、Pub/Sub から通知を受け取ることができます。各イベントには固有のイベントタイプがあります。次の表に、イベントのタイプと、それ対応する定義を示します。

イベントの種類 説明
CreateRepo ユーザーがリポジトリを作成したときに発生します。
RefUpdate ユーザーが git push コマンドを実行したときに発生します。
DeleteRepo ユーザーがリポジトリを削除したときに発生します。

通知形式

次のいずれかの形式で通知を行うように Pub/Sub を構成できます。

  • JSON
  • プロトコル バッファ

通知データ

各 Pub/Sub 通知には、イベントに関する以下の情報が含まれます。

フィールド名 説明
name リポジトリの名前。
URL リポジトリの URL。
eventTime 変更が発生した時間。
refUpdateEvent 特定の変更に関する情報。
createRepoEvent ユーザーがリポジトリを作成したかどうかを示します。
deleteRepoEvent ユーザーがリポジトリを削除したかどうかを示します。

通知が git push コマンドに関するものである場合、この通知の refUpdateEvent フィールドに以下の情報が含まれます。

フィールド名 説明
メール 変更を行なったユーザーのメールアドレス。
refUpdates commit に関する情報。

refUpdates フィールドには、git push コマンドに関する次の情報が含まれます。

フィールド名 説明
refName ブランチの名前。
updateType 更新のタイプ。詳細については、更新タイプをご覧ください。
oldId リポジトリの以前の commit ID。
newId リポジトリの新しい ID。

更新タイプ

git push イベントの更新タイプは、次の 4 つのうちのいずれかとなります。タイプは、通知の updateType フィールドで確認できます。

更新タイプ 説明
作成 コマンドが新しいリファレンスを作成したときに発生します。
UPDATE_FAST_FORWARD コマンドがオブジェクトを更新したときに発生します。
UPDATE_NON_FAST_FORWARD コマンドが -f フラグ(git push -f など)を使用したときに発生します。
削除 コマンドがリファレンスを削除したときに発生します。

通知の例

次に、Pub/Sub 通知に含まれるデータの例を示します。この通知では、JSON 形式を使用しています。

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

クロス プロジェクトの設定例

別のプロジェクトのトピックにメッセージを公開するように、Cloud Source Repositories を構成できます。この場合、リポジトリが存在するプロジェクトにサービス アカウントを作成する必要があります。Pub/Sub トピックを含むプロジェクトで、このサービス アカウントに roles/pubsub.publisher 役割を付与します。このアカウントと Pub/Sub トピックで Cloud Source Repositories を構成すると、リポジトリのイベント メッセージが別のプロジェクトのトピックに表示されます。