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 フィールドに以下の情報が含まれます。

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

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

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

更新タイプ

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

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

通知の例

次に、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 を構成すると、リポジトリのイベントメッセージが別のプロジェクトのトピックに表示されます。