Cloud Build に接続する

このページでは、Secure Source Manager リポジトリの Cloud Build 構成ファイルとトリガー YAML ファイルを使用して、Secure Source Manager からビルドを自動的に呼び出す方法について説明します。

デフォルトでは、Secure Source Manager は Google マネージド サービス エージェントを使用して Cloud Build や他のリソースとやり取りします。チームの権限を分離するには、ユーザー管理のサービス アカウントをリポジトリに関連付けて、リポジトリごとの ID を構成することをおすすめします。Secure Source Manager は、リポジトリに関連付けられたユーザー管理のサービス アカウントを使用してビルドをトリガーします。

デフォルトのサービス エージェントとは異なり、カスタム Cloud Build サービス アカウントに対する iam.serviceAccounts.actAs 権限を使用して、ユーザー管理のサービス アカウントを構成できます。これにより、ビルド権限をそのリポジトリに制限したまま、カスタム サービス アカウントを使用してビルドを実行できます。

始める前に

  1. Secure Source Manager インスタンスを作成します。
  2. Secure Source Manager リポジトリを作成します。

  3. Cloud Build ユーザー指定のサービス アカウントを構成します。 Cloud Build が Secure Source Manager リポジトリから読み取れるようにするには、 Cloud Build サービス アカウント（デフォルトのサービス アカウントまたはユーザー管理のサービス アカウント）に次のロールを付与します。

    • Secure Source Manager インスタンスに対するSecure Source Manager インスタンス アクセサー （roles/securesourcemanager.instanceAccessor）。
    • リポジトリに対するSecure Source Manager リポジトリ閲覧者 。

    ユースケースによっては、Cloud Build サービス アカウントに追加のロールが必要になる場合があります。次に例を示します。

    • ビルドログを Cloud Logging に保存するには、Cloud Build サービス アカウントにログ書き込み ロール（roles/logging.logWriter）を付与します。
    • Secret Manager のシークレットにアクセスするには、Cloud Build サービス アカウントにSecret Manager のシークレット アクセサー （roles/secretmanager.secretAccessor）ロールを付与します。

    ビルドログについては、ビルドログの設定をご覧ください。

  4. ビルドがワーカープールで実行される場合は、ビルドが実行されるプロジェクトのリポジトリのユーザー管理サービス アカウントにCloud Build WorkerPool ユーザー ロール（roles/cloudbuild.workerPoolUser）を付与します。

必要なロール

Secure Source Manager リポジトリを Cloud Build に接続するために必要な権限を取得するには、管理者に次の IAM ロールを付与するよう依頼してください。

ロールの付与については、プロジェクト、フォルダ、組織へのアクセス権の管理をご覧ください。

必要な権限は、カスタム ロールや他の事前定義 ロールから取得することもできます。

Secure Source Manager ロールの付与については、 IAM によるアクセス制御と ユーザーにインスタンスへのアクセス権を付与するをご覧ください。

必要なサービス アカウントのロール

Secure Source Manager を Cloud Build に接続するには、リポジトリごとの ID の IAM 権限を構成する必要があります。

リポジトリごとの ID の設定

リポジトリごとの ID を使用するには、権限を構成する必要があります。

  1. ユーザー: リポジトリ サービス アカウントを構成するユーザーには、 ユーザー管理のサービス アカウントに対するサービス アカウント ユーザー ロール（roles/iam.serviceAccountUser）が必要です。この権限は、リポジトリの作成時または更新時に確認されます。

  2. Secure Source Manager サービス エージェント: リポジトリ プロジェクトの Secure Source Manager サービス エージェントに、ユーザー管理のサービス アカウントに対する サービス アカウント トークン作成者 ロール（roles/iam.serviceAccountTokenCreator）を付与します。

    Secure Source Manager サービス エージェントのメールアドレスの形式は service-REPOSITORY_PROJECT_NUMBER@gcp-sa-sourcemanager.iam.gserviceaccount.com です。 ここで REPOSITORY_PROJECT_NUMBER はリポジトリをホストするプロジェクトのプロジェクト番号です。

  3. ユーザー管理のサービス アカウント:

    • ユーザー管理のサービス アカウントに、カスタム Cloud Build サービス アカウント（リポジトリ プロジェクト内）に対するサービス アカウント ユーザー ロール（roles/iam.serviceAccountUser）を付与します。
    • ユーザー管理のサービス アカウントに、ビルドが実行されるプロジェクトに対するCloud Build 編集者 ロール（roles/cloudbuild.builds.editor）とService Usage 消費者 ロール（roles/serviceusage.serviceUsageConsumer）を付与します。

IAM ロールを付与する方法については、単一のロールの付与または取り消しをご覧ください。

ビルド構成ファイルを作成する

ビルド構成ファイルでは、Cloud Build がビルドタスクを実行するために必要なフィールドを定義します。ビルド構成ファイルは YAML 構文で記述します。

ビルド構成ファイルは、ビルド元となるブランチに作成できます。

ビルド構成ファイルを作成する手順は次のとおりです。

  1. Secure Source Manager ウェブ インターフェースで、Cloud Build に接続するリポジトリを選択します。
  2. Cloud Build を使用してビルドするブランチを選択します。

  3. ビルド構成ファイルを作成します。ビルド構成ファイルの作成方法については、ビルド構成ファイルを作成するの手順に沿って操作してください。

  4. 変更をブランチに commit します。

トリガー ファイルを作成する

トリガー構成ファイルは、リポジトリのデフォルト ブランチ に作成する必要があります。

トリガー構成ファイルを作成する手順は次のとおりです。

  1. ローカル リポジトリまたは Secure Source Manager ウェブ インターフェースで、デフォルト ブランチ に切り替えます。

  2. .cloudbuild/triggers.yaml という名前のファイルを作成します。

  3. .cloudbuild/triggers.yaml ファイルでトリガーを構成します。

    triggers:
- name: TRIGGER_NAME
  project: PROJECT_ID
  configFilePath: CLOUD_BUILD_CONFIG_PATH
  eventType: EVENT_TYPE
  ignoredGitRefs: IGNORED_GIT_REFS
  includedGitRefs: INCLUDED_GIT_REFS
  serviceAccount: SERVICE_ACCOUNT
  includedFiles: INCLUDED_FILES
  ignoredFiles: IGNORED_FILES
  disabled: DISABLED_BOOL
  substitutions:
    _VARIABLE_NAME: VARIABLE_VALUE
    OVERRIDE_VARIABLE_NAME: OVERRIDE_VARIABLE_VALUE

    次のように置き換えます。

    • TRIGGER_NAME は、トリガーの名前に置き換えます。トリガー名に使用できるのは、英数字とハイフンのみです。ハイフンで始まる、またはハイフンで終わる名前は使用できません。トリガー名は 64 文字未満にする必要があります。
    • PROJECT_ID は、Cloud Build を Google Cloud 有効にした プロジェクト ID に置き換えます。このフィールドは省略可能です。デフォルトは Secure Source Manager プロジェクトです。
    • CLOUD_BUILD_CONFIG_PATH は、このトリガーに使用する Cloud Build 構成ファイルのパスに置き換えます。 このフィールドは省略可能です。デフォルト値は .cloudbuild/cloudbuild.yaml です。

    • EVENT_TYPE は、ビルドをトリガーするイベントタイプに置き換えます。オプションは次のとおりです。

      • push: 指定したブランチへの push でトリガーする
      • pull_request : 指定したブランチへの pull リクエストでトリガーする

      このフィールドは省略可能です。デフォルト値は push です。

    • INCLUDED_GIT_REFS は、ビルドをトリガーする Git 参照に一致する RE2 正規表現形式（省略可）に置き換えます。デフォルト値は空です。空の値は、制限がないことを示します。

    • IGNORED_GIT_REFS は、ビルドをトリガーしない Git 参照に一致する RE2 正規表現形式の正規表現（省略可）に置き換えます。デフォルト値は空です。空の値は、制限がないことを示します。ignoredGitRefs フィールドは、includedGitRefs フィールドの前にチェックされます。これらのフィールドの詳細については、 トリガー ファイルのスキーマをご覧ください。

    • SERVICE_ACCOUNT は、ビルドに使用する Cloud Build サービス アカウントに置き換えます。形式は projects/PROJECT_ID/serviceAccounts/ACCOUNT です。ACCOUNT は、 サービス アカウントのメールアドレスまたは一意の ID に置き換えます。デフォルトの Cloud Build サービス アカウントまたはユーザー管理のサービス アカウントを使用できます。 以前の Cloud Build サービス アカウントは、制限があるため使用できません。

    • INCLUDED_FILES は、ビルドをトリガーするファイルに一致する RE2 形式の正規表現（省略可）に置き換えます。

      変更されたファイルが ignoredFiles フィルタ フィールドと一致せず、includedFiles フィルタ フィールドと一致する場合、ビルドがトリガーされます。デフォルト値は空です。空の値は、制限がないことを示します。

    • IGNORED_FILES は、ビルドをトリガーしないファイルに一致する RE2 形式の正規表現（省略可）に置き換えます。

      commit 内の変更されたファイルがすべてこのフィルタ フィールドと一致する場合、ビルドはトリガーされません。デフォルト値は空です。空の値は、制限がないことを示します。

    • DISABLED_BOOL は、トリガーを無効にする場合は true、トリガーを有効にする場合は false に置き換えます。このフィールドは省略可能です。デフォルト値は false です。

    • VARIABLE_NAME は、トリガー ファイルに導入する変数の名前に置き換えます。

    • VARIABLE_VALUE は、変数の値に置き換えます。

    • OVERRIDE_VARIABLE_NAME は、Secure Source Manager のデフォルトの置換変数名に置き換えます。使用可能な デフォルトの置換変数については、 トリガー ファイルのスキーマの置換をご覧ください。

    • OVERRIDE_VARIABLE_VALUE は、デフォルトの置換変数のデフォルト値をオーバーライドする値に置き換えます。

  4. トリガー構成ファイルをデフォルト ブランチに commit します。

    トリガー ファイルが commit されると、Secure Source Manager はトリガー ファイルの構成に基づいてビルドをトリガーします。

    Secure Source Manager は、次のイベントタイプの構成ファイルと、関連する commit SHA または Git 参照を読み取ります。

    • push イベントの場合、Secure Source Manager は push が完了したときに commit SHA または Git 参照を読み取ります。
    • pull_request イベントの場合、Secure Source Manager は pull リクエストの変更が pull されたときに commit SHA または Git 参照を読み取ります。

ビルドのステータスを表示する

push イベントまたは pull リクエスト イベントによってビルドがトリガーされると、commit とビルドのステータスが Secure Source Manager ウェブ インターフェースに表示されます。

ビルドのステータスの値は次のとおりです。

  • 成功SUCCESS: ビルドが正常に完了しました。
  • 警告WARNING: ビルドを試行中に問題が発生しました。
  • failureFAILURE: 実行中にビルドが失敗しました。

ビルドが失敗した commit が重要なブランチにマージされないようにするには、トリガー ファイルで構成されたトリガーからのステータス チェックが成功することを要求するブランチ保護ルールを構成します。ブランチ保護の詳細については、 ブランチ保護の概要をご覧ください。

push イベントのビルドステータスを表示する手順は次のとおりです。

  1. Secure Source Manager ウェブ インターフェースで、リポジトリに移動します。

    最新の push イベントでビルドがトリガーされた場合、ステータスが commit SHA の横に表示されます。ステータスの詳細を表示するには、ステータスをクリックします。

  2. 以前の commit のビルドステータスを表示するには、[Commits] を選択して commit 履歴を表示し、詳細を表示するステータスをクリックします。

pull リクエスト イベントのビルドステータスを表示する手順は次のとおりです。

  1. Secure Source Manager ウェブ インターフェースで、[Pull requests] をクリックします。

  2. 表示する pull リクエストをクリックします。

    pull リクエストによってビルドがトリガーされた場合は、 [All checks were successful] または [Some checks reported warnings] というタイトルのセクションが表示されます。

トラブルシューティング

Secure Source Manager との接続時に Cloud Build エラーを診断して解決する方法については、 トリガー ファイルでビルドがトリガーされないをご覧ください。

次のステップ