GitHub の問題に関する通知を構成する

Cloud Build は、選択したチャネルに通知を送信することで、ビルド更新を通知します。このページでは、GitHub Issues Notifier を使用して通知を構成する方法について説明します。

始める前に

Enable the Cloud Build, Compute Engine, Cloud Run, Pub/Sub, and Secret Manager APIs.
Enable the APIs

Google Cloud CLI をインストールする。

GitHub Issues の通知の構成

次のセクションでは、GitHub Issues Notifier を使用して GitHub の問題の通知を手動で構成する方法について説明します。構成を手動で行わず、自動化する場合は、通知の構成の自動化をご覧ください。

GitHub Issues を構成するには:

GitHub 個人アクセストークンを作成します。
1. 新しいトークンを作成するために、GitHub の設定に移動します。
2. [repo範囲] を選択します。
  
  注: これにより、リポジトリ（プライベートリポジトリを含む）に対する完全アクセス権が付与されます。
3. [Generate token] をクリックします
Secret Manager に GitHub トークンを保存します。
1. Google Cloud コンソールで [シークレットマネージャー] ページを開きます。
  
  [Secret Manager] ページを開く
2. [シークレットの作成] をクリックします。
3. シークレットの名前を入力します。
4. [シークレットの値] で、GitHub トークンを追加します。
5. シークレットを保存するには、[シークレットの作成] をクリックします。
Cloud Run サービスアカウントにはプロジェクトの編集者ロールが存在する場合がありますが、編集者ロールは Secret Manager のシークレットにアクセスするのには不十分です。Cloud Run サービスアカウントにシークレットへのアクセス権を付与する必要があります。
1. Google Cloud コンソールで [IAM] ページに移動します。
  
  [IAM] ページを開く
2. プロジェクトに関連付けられている Compute Engine のデフォルトのサービスアカウントを見つけます。
  
  Compute Engine のデフォルトのサービスアカウントは次のようになります。
```
project-number-compute@developer.gserviceaccount.com
```
  Compute Engine のデフォルトのサービスアカウントをメモしておきます。
  
  注: デフォルトでは、Cloud Run は Compute Engine のデフォルトのサービスアカウントで Notifier イメージを実行し、シークレットを取得します。ランタイムサービスアカウントの詳細については、ランタイムサービスアカウントをご覧ください。
3. Google Cloud コンソールで [Secret Manager] ページを開きます。
  
  [シークレットマネージャー] ページを開く
4. GitHub トークンを含むシークレット名をクリックします。
5. [権限] タブで、[メンバーを追加] をクリックします。
6. プロジェクトに関連付けられている Compute Engine のデフォルトのサービスアカウントをメンバーとして追加します。
7. ロールとして Secret Manager のシークレットアクセサー権限を選択します。
8. [保存] をクリックします。
Cloud Run サービスアカウントに、Cloud Storage バケットの読み取り権限を付与します。
1. Google Cloud コンソールで [IAM] ページに移動します。
  
  [IAM] ページを開く
2. プロジェクトに関連付けられている Compute Engine のデフォルトのサービスアカウントを見つけます。
  
  Compute Engine のデフォルトのサービスアカウントは次のようになります。
```
project-number-compute@developer.gserviceaccount.com
```
3. Compute Engine のデフォルトのサービスアカウントを含む行の鉛筆アイコンをクリックします。[アクセスを編集] タブが表示されます。
4. [別のロールを追加] をクリックします。
5. 次のロールを追加します。
  - ストレージオブジェクト閲覧者
  注: プロジェクトレベルではなくバケットレベルで権限を付与する場合は、バケットを作成する際に Storage レガシーオブジェクトオーナーのロールをそのバケットに追加します。詳しくは、プロジェクトレベルのロールとバケットレベルのロールをご覧ください。
6. [保存] をクリックします。
テンプレート構成ファイルを作成し、作成された GitHub Issues の形式を記述します。

次のテンプレート構成ファイルの例では、title フィールドと body フィールドでビルドの置換変数が使用されています。
```
{
    "title": "Build {{.Build.BuildTriggerId}}: {{.Build.Status}}",
    "body": "[{{.Build.ProjectId}}] {{.Build.BuildTriggerId}} status: **{{.Build.Status}}**\n\n[View Logs]({{.Build.LogUrl}})"
}
```
サンプルについては、GitHub Issues Notifier のテンプレート構成ファイルをご覧ください。

問題を作成するための GitHub API エンドポイントの利用可能な本文パラメータから追加のフィールドを設定できます。
Notifier 構成ファイルを作成し、ビルドイベントに GitHub Issues Notifier とフィルタを構成します。

次の Notifier 構成ファイルの例では、filter フィールドで Common Expression Language を使用し、変数 build を指定し、SUCCESS ステータスでビルドイベントをフィルタリングします。
```
apiVersion: cloud-build-notifiers/v1
kind: GitHubIssuesNotifier
metadata:
  name: example-githubissues-notifier
spec:
  notification:
    filter: build.status == Build.Status.FAILURE
    template: 
      type: golang
      uri: gs://bucket_name/template-file-name
    delivery:
      githubToken:
        secretRef: github-token
      githubRepo: myuser/myrepo
  secrets:
  - name: github-token
    value: projects/project-id/secrets/secret-name/versions/latest
```
ここで
- githubToken は、この例で使用されている構成変数です。Secret Manager に格納されている GitHub トークンを参照します。ここで指定する変数名は、secrets の name フィールドに一致させる必要があります。
- bucket-name はバケットの名前です。
- template-file-name はテンプレートファイルの名前です。
- myuser/myrepo は、問題が作成されるリポジトリの名前です。
- project-id は、Google Cloud プロジェクトの ID です。
- secret-name は、GitHub トークンを含むシークレットの名前です。
サンプルについては、GitHub Issues Notifier の Notifier 構成ファイルをご覧ください。

フィルタに使用できるその他のフィールドについては、ビルドリソースをご覧ください。フィルタリングに関するその他の例については、CEL を使用してビルドイベントをフィルタリングするをご覧ください。
通知機能構成ファイルとテンプレートファイルを Cloud Storage バケットにアップロードします。
1. Cloud Storage バケットがない場合は、次のコマンドを実行してバケットを作成します。ここで、bucket-name は命名要件に従って、バケットに付ける名前です。
```
gcloud storage buckets create gs://bucket-name/
```
2. Notifier 構成ファイルとテンプレートファイルをバケットにアップロードします。
```
gcloud storage cp config-file-name gs://bucket-name/config-file-name

gcloud storage cp config-file-name gs://bucket-name/config-file-name
```
  ここで
  - bucket-name はバケットの名前です。
  - config-file-name は構成ファイルの名前です。
  - template-file-name はテンプレートファイルの名前です。
Notifier を Cloud Run にデプロイします。
```
 gcloud run deploy service-name \
   --image=us-east1-docker.pkg.dev/gcb-release/cloud-build-notifiers/githubissues:latest \
   --no-allow-unauthenticated \
   --update-env-vars=CONFIG_PATH=config-path,PROJECT_ID=project-id
```
ここで
- service-name は、イメージをデプロイする Cloud Run サービスの名前です。
  
  注: service-name は、作成する新しい通知者サービスを参照します。
- config-path は、GitHub Issues Notifier gs://bucket-name/config-file-name の Notifier 構成ファイルのパスです。
- project-id は、Google Cloud プロジェクトの ID です。
gcloud run deploy コマンドは、Cloud Build が所有する Artifact Registry からホストされたイメージの最新バージョンを pull します。Cloud Build は 9 か月間、Notifier イメージをサポートします。9 か月を過ぎると、イメージのバージョンは削除されます。以前のイメージバージョンを使用する場合は、gcloud run deploy コマンドの image 属性でイメージタグの完全なセマンティックバージョンを指定する必要があります。以前のイメージバージョンとタグは、Artifact Registry にあります。

注: このコマンドの実行中に、--region や --platform などの追加の引数を指定するよう求められる場合があります。gcloud run deploy コマンドに渡すことができるパラメータの詳細については、Cloud Run へのデプロイをご覧ください。このコマンドを使用して Notifier をデプロイできない場合は、Cloud Run のトラブルシューティングガイドでデプロイエラーを解決する方法を確認してください。
プロジェクトに認証トークンを作成する Pub/Sub 権限を付与します。
```
 gcloud projects add-iam-policy-binding project-id \
   --member=serviceAccount:service-project-number@gcp-sa-pubsub.iam.gserviceaccount.com \
   --role=roles/iam.serviceAccountTokenCreator
```
ここで
- project-id は、Google Cloud プロジェクトの ID です。
- project-number は Google Cloud プロジェクト番号です。
注: プロジェクトに Pub/Sub サービスアカウントが存在しない場合は、サブスクリプションを作成して使用するをご覧ください。
Pub/Sub サブスクリプション ID を表すサービスアカウントを作成します。
```
gcloud iam service-accounts create cloud-run-pubsub-invoker \
  --display-name "Cloud Run Pub/Sub Invoker"
```
cloud-run-pubsub-invoker を使用するか、Google Cloud プロジェクト内で一意の名前を使用します。
cloud-run-pubsub-invoker サービスアカウントに Cloud Run Invoker 権限を付与します。
```
gcloud run services add-iam-policy-binding service-name \
   --member=serviceAccount:cloud-run-pubsub-invoker@project-id.iam.gserviceaccount.com \
   --role=roles/run.invoker
```
ここで
- service-name は、イメージをデプロイする Cloud Run サービスの名前です。
- project-id は、Google Cloud プロジェクトの ID です。
cloud-builds トピックを作成して、Notifier のビルド更新メッセージを受信します。
```
gcloud pubsub topics create cloud-builds
```
Notifier に Pub/Sub push サブスクライバーを作成します。
```
 gcloud pubsub subscriptions create subscriber-id \
   --topic=cloud-builds \
   --push-endpoint=service-url \
   --push-auth-service-account=cloud-run-pubsub-invoker@project-id.iam.gserviceaccount.com
```
ここで
- subscriber-id は、サブスクリプションに付ける名前です。
- service-url は、Cloud Run によって生成された、新しいサービスの URL です。
- project-id は、Google Cloud プロジェクトの ID です。

これで Cloud Build プロジェクトの通知が設定されました。次にビルドを呼び出したときに、構成したフィルタとビルドが一致すると、定義した GitHub リポジトリに対して問題が作成されます。

CEL を使用したビルドイベントのフィルタリング

Cloud Build は、ビルドリソースにリストされているフィールドの変数 build で CEL を使用して、トリガー ID、イメージリスト、置換変数などのビルドイベントと関連するフィールドにアクセスします。filter 文字列を使用すると、Build リソースに表示されているフィールドを使用してビルド構成ファイル内のビルドイベントをフィルタリングできます。フィールドに関連付けられた正確な構文を見つけるには、cloudbuild.proto ファイルをご覧ください。

トリガー ID によるフィルタリング

トリガー ID でフィルタリングするには、build.build_trigger_id を使用してトリガー ID の値をfilter フィールドに指定します。ここで、trigger-id は文字列であるトリガー ID です。

filter: build.build_trigger_id == trigger-id

ステータスによるフィルタリング

ステータスでフィルタリングするには、build.status を使用して、フィルタリングするビルドのステータスを filter フィールドに指定します。

次の例は、filter フィールドを使用して SUCCESS ステータスのビルドイベントをフィルタリングする方法を示しています。

filter: build.status == Build.Status.SUCCESS

さまざまなステータスのビルドをフィルタリングすることもできます。次の例は、filter フィールドを使用して、ステータスが SUCCESS、FAILURE、または TIMEOUT のビルドイベントをフィルタリングする方法を示しています。

filter: build.status in [Build.Status.SUCCESS, Build.Status.FAILURE, Build.Status.TIMEOUT]

フィルタリングできるその他のステータス値を確認するには、ビルドリソースリファレンスのステータスをご覧ください。

タグによるフィルタリング

タグでフィルタリングするには、build.tags を使用して filter フィールドにタグの値を指定します。ここで、tag-name はタグの名前です。

filter: tag-name in build.tags

size を使用すると、ビルドイベントで指定されたタグの数に基づいてフィルタリングできます。以下の例では、filter フィールドにより、1 つのタグが v1 に指定されたタグがちょうど 2 つあるビルドイベントがフィルタリングされます。

filter: size(build.tags) == 2 && "v1" in build.tags

イメージによるフィルタリング

イメージでフィルタリングするには、build.images を使用して filter フィールドにイメージの値を指定します。ここで image-name は、us-east1-docker.pkg.dev/my-project/docker-repo/image-one などの Artifact Registry に表示されるイメージの完全な名前です。

filter: image-name in build.images

下の例では、filter がイメージ名として us-east1-docker.pkg.dev/my-project/docker-repo/image-one または us-east1-docker.pkg.dev/my-project/docker-repo/image-two が指定されているビルドイベントをフィルタリングします。

filter: "us-east1-docker.pkg.dev/my-project/docker-repo/image-one" in build.images || "us-east1-docker.pkg.dev/my-project/docker-repo/image-one" in build.images

時間によるフィルタリング

filter フィールドに build.create_time、build.start_time、build.finish_time のいずれかのオプションを指定すると、ビルドの作成時間、開始時間、終了時間に基づいてビルドイベントをフィルタリングできます。

下の例では、filter フィールドで timestamp を使用し、ビルドを作成するリクエスト時刻を 2020 年 7 月 20 日午前 6 時に指定して、ビルドイベントをフィルタリングします。

filter: build.create_time == timestamp("2020-07-20:T06:00:00Z")

時刻の比較によりビルドイベントをフィルタリングすることもできます。下の例では、filter フィールドで timestamp を使用し、開始時刻を 2020 年 7 月 20 日午前 6 時と 2020 年 7 月 30 日午前 6 時の間に指定して、ビルドイベントをフィルタリングします。

filter: timestamp("2020-07-20:T06:00:00Z") >= build.start_time && build.start_time <= timestamp("2020-07-30:T06:00:00Z")

CEL での時間帯の表記方法に関する詳細については、時間帯の言語の定義をご覧ください。

ビルド時間でフィルタリングするには、duration を使用してタイムスタンプを比較します。下の例では、filter フィールドで duration を使用して、ビルドが 5 分以上実行されるビルドイベントをフィルタリングします。

filter: build.finish_time - build.start_time >= duration("5m")

置換によるフィルタリング

build.substitutions を使用して filter フィールドに置換変数を指定すると、置換によってフィルタリングできます。次の例では、filter フィールドは置換変数 substitution-variable を含むビルドを一覧表示し、substitution-variable が指定された substitution-value と一致するかどうかを確認します。

filter: build.substitutions[substitution-variable] == substitution-value

ここで

substitution-variable は置換変数の名前です。
substitution-value は、置換値の名前です。

また、デフォルトの置換変数値でフィルタリングすることもできます。次の例では、filter フィールドにブランチ名が master のビルドとリポジトリ名が github.com/user/my-example-repo のビルドが一覧表示されます。デフォルトの置換変数 BRANCH_NAME と REPO_NAME がキーとして build.substitutions に渡されます。

filter: build.substitutions["BRANCH_NAME"] == "master" && build.substitutions["REPO_NAME"] == "github.com/user/my-example-repo"

正規表現を使用して文字列をフィルタリングする場合は、組み込みの matches 関数を使用できます。以下の例では、filter フィールドは、ステータスが FAILURE または TIMEOUT であり、正規表現 v{DIGIT}.{DIGIT}.{3 DIGITS}) と一致する値を持つビルド置換変数 TAG_NAME のあるビルドでフィルタリングします。

filter: build.status in [Build.Status.FAILURE, Build.Status.TIMEOUT] && build.substitutions["TAG_NAME"].matches("^v\\d{1}\\.\\d{1}\\.\\d{3}$")

デフォルトの置換値のリストについては、デフォルトの置換の使用をご覧ください。

次のステップ

Cloud Build Notifier の詳細を確認します。
ビルド通知をサブスクライブする方法を学習する。
Cloud Build ビルド構成ファイルを作成する方法を学習する。