ビルドトリガーの作成と管理

ソースコードを変更するたびに、Cloud Build トリガーが自動的にビルドを開始します。ソース リポジトリが変更された場合や、特定の条件に一致する変更があった場合にコードをビルドするようにトリガーを構成できます。

このページでは、GitHub や Bitbucket などのソース リポジトリに接続し、リポジトリにコードをビルドするビルドトリガーを作成する方法について説明します。

始める前に

  • Cloud Build API を有効にします。

    API を有効にする

  • トリガーを作成するには、プロジェクトの Cloud Build 編集者roles/cloudbuild.builds.editor)のロールが必要です。
  • Cloud Source Repositories、GitHub または Bitbucket にソースコードが必要です。
  • Dockerfile または Cloud Build 構成ファイルのいずれかが必要です。

ソース リポジトリに接続する

リポジトリにコードを作成する前に、Cloud Build をソース リポジトリに接続する必要があります。Cloud Source Repositories のリポジトリはデフォルトで Cloud Build に接続されます。手動で接続しなくても、Cloud Source Repositories にリポジトリのトリガーを直接作成できます。

GitHub や Bitbucket でホストされているような外部リポジトリを接続する場合は、最初にリポジトリを Cloud Build に接続するために、リポジトリに対する管理者レベルの権限が必要です。すでに Cloud Build に接続されているリポジトリにトリガーを作成する場合、管理者権限は必要ありません。

GitHub または Bitbucket に接続するには、次の手順を実行します。

  1. Google Cloud Console で [トリガー] ページを開きます。

    [トリガー] ページを開く

  2. プロジェクトを選択し、[開く] をクリックします。

  3. [リージョン] プルダウン メニューから、トリガーを作成するリージョンを選択します。

  4. [リポジトリを接続] をクリックします。

  5. ソースコードを保存したリポジトリを選択します。

    ソース リポジトリとして [GitHub(ミラーリング済み)] または [Bitbucket(ミラーリング済み)] を選択すると、Cloud Build は Cloud Source Repositories にリポジトリをミラーリングし、すべてのオペレーションにミラーリング済みのリポジトリを使用します。

  6. [続行] をクリックします。

  7. ユーザー名とパスワードを使用して、ソース リポジトリに対する認証を行います。

  8. 使用可能なリポジトリのリストからリポジトリを選択して、[接続] をクリックします。

    GitHub や Bitbucket などの外部リポジトリを使用するには、作業中の Google Cloud プロジェクトでオーナーレベルの権限が必要になります。

  9. リポジトリのソースコードを自動的にビルドするビルドトリガーの作成を続けるには、[トリガーを作成する] をクリックします。継続しない場合は [完了] をクリックします。

ビルドトリガーの作成

コンソール

  1. Google Cloud Console で [トリガー] ページを開きます。

    [トリガー] ページを開く

  2. ページの上部にあるプロジェクト セレクタのプルダウン メニューからプロジェクトを選択します。

  3. [開く] をクリックします。

  4. [トリガーを作成] をクリックします。

  5. 次のトリガー設定を入力します。

    • 名前: トリガーの名前を入力します。

    • リージョン: トリガーのリージョンを選択します。

      トリガーに関連付けられたビルド構成ファイルでプライベート プールが指定されている場合、トリガーに選択するリージョンはプライベート プールのリージョンと一致する必要があります。

      リージョンとして global を選択した場合、Cloud Build はビルド構成ファイルで指定されたリージョンを使用してビルドを実行します。ビルド構成ファイルでプライベート プールを指定した場合はプライベート プールのリージョンになりますが、プライベート プールを指定しない場合はグローバル デフォルト プールになります。

    • 説明(省略可): トリガーの説明を入力します。

    • イベント: トリガーを起動するリポジトリ イベントを選択します。

      • ブランチに push する: 特定のブランチに対して commit が行われたときにビルドを開始するトリガーを設定します。

      • 新しいタグを push する: 特定のタグを含む commit が行われたときにビルドを開始するトリガーを設定します。

      • pull リクエスト: pull リクエストの commit が行われたときにビルドを開始するトリガーを設定します。

    • ソース: ソースとして [第 1 世代] または [第 2 世代] を選択します。ソースとして [第 2 世代] を選択した場合は、GitHub と GitHub Enterprise のリポジトリのみを接続できます。詳細については、Cloud Build リポジトリをご覧ください。

      • リポジトリ: 使用可能なリポジトリのリストから目的のリポジトリを選択します。新しいリポジトリに接続するには、ソース リポジトリへの接続をご覧ください。
      • ブランチまたはタグ: ブランチまたはタグの値にマッチングさせる正規表現を指定します。タグではスラッシュ(/)を使用できません。有効な正規表現の構文については、RE2 構文をご覧ください。

        ビルドを実行すると、Cloud Build は、リポジトリの内容を Cloud Build のデフォルトの作業ディレクトリ(/workspace)にコピーします。作業ディレクトリについて詳しくは、ビルド構成の概要ページをご覧ください。

        特定のソースからのビルドのみを許可するには、許可された統合(constraints/cloudbuild.allowedIntegrations)の組織のポリシーを設定して、トリガーで定義されたソースとのやり取りを拒否します。組織のポリシーによってトリガーがオーバーライドされ、ビルドは実行されません。詳しくは、プロジェクトの組織のポリシーのゲートビルドをご覧ください。

    • 含まれるファイル(省略可): 少なくとも 1 つのファイルに影響する変更があった場合は、ビルドが開始されます。glob 文字列で、ワイルドカード文字を使用して複数のファイルを指定できます。使用できるワイルドカード文字は、Go Match でサポートされる文字、**オルタネイションなどです。

    • 無視されるファイル(省略可): 無視されるファイルにのみ影響する変更があった場合は、ビルドが開始されません。glob 文字列で、ワイルドカード文字を使用して複数のファイルを指定できます。使用できるワイルドカード文字は、Go Match でサポートされる文字、**オルタネイションなどです。

      含まれているファイル無視されるファイルの両方で同じファイルを指定した場合、そのファイルを変更してもビルドは呼び出されません。たとえば、すべてのディレクトリ内の README.md を無視するために無視されるファイル**/README.md を指定し、src/ フォルダ内の任意のファイルへの変更でビルドを開始するために含まれているファイルsrc/* を指定したとします。ここで、src/README.md に変更を加えた場合、Cloud Build はビルドを開始しません。変更をソースに push するたびに、Cloud Build は変更されたファイルについて、含まれているファイルと無視されるファイルを検索し、ビルドを呼び出すかどうかを決定します。

      • 既存のブランチのリポジトリに変更を push した場合、Cloud Build は push したばかりの commit と以前にそのブランチが指していた commit の間で、変更されたファイルを調べます。
      • リポジトリが Cloud Source Repositories のリポジトリで、新しく作成したブランチに変更を push すると、Cloud Build は、リポジトリ内のすべてのファイルを変更されたファイルとして扱います。
      • ブランチを削除した場合、Cloud Build はビルドを開始しません。
    • 構成: ビルドに使用するリモート リポジトリにあるビルド構成ファイルを選択するか、インライン ビルド構成ファイルを作成します。

      • タイプ: ビルドに使用する構成のタイプを選択します。
        • Cloud Build 構成ファイル(yaml または json): 構成にビルド構成ファイルを使用します。
        • Dockerfile: 構成には Dockerfile を使用します。
        • Buildpacks: 構成には Buildpacks を使用します。
      • 場所: 構成の場所を指定します。

        • リポジトリ: 構成ファイルがリモート リポジトリにある場合は、ビルド構成ファイルDockerfile ディレクトリの場所、または Bullpack のディレクトリを指定します。ビルド構成タイプが Dockerfile または buildpack の場合、ビルドするイメージの名前と、必要に応じてビルドのタイムアウトを指定する必要があります。Dockerfile または buildpack イメージ名を指定すると、ビルドが実行される docker build または pack コマンドのプレビューが表示されます。
        • buildpack の環境変数(省略可): 構成タイプとして buildpacks を選択した場合、[パック環境変数を追加] をクリックして buildpack 環境変数と値を指定します。buildpack 環境変数の詳細については、環境変数をご覧ください。
        • インライン: 構成オプションとして Cloud Build 構成ファイル(yaml または json)を選択した場合、インライン ビルド構成を指定できます。Google Cloud Console で [エディタを開く] をクリックして、YAML または JSON 構文でビルド構成ファイルを書き込みます。[完了] をクリックしてビルド構成ファイルを保存します。

    • プライベート プールを使用: このフィールドは、[構成] オプションとして [Dockerfile] を選択した場合に表示されます。プライベート プールでビルドを実行する場合は、このチェックボックスをオンにします。

    • プライベート プール: [プライベート プールを使用] を選択した場合は、projects/WORKERPOOL_PROJECT_ID/locations/REGION/workerPools/WORKERPOOL_ID 形式のプライベート プールのリソース名を指定します。

    • 代入変数(省略可): ビルドの構成オプションとして Cloud Build 構成ファイルを選択した場合、このフィールドを使用して、トリガー固有の代入変数を定義できます。たとえば、複数のトリガーを作成し、それぞれのトリガーが特定の環境にアプリをデプロイするとします。この場合、アプリケーションが 1 つの環境にデプロイされることをビルド構成ファイルに指定し、このフィールドを使用して代入変数を定義して、このトリガーがデプロイされる環境を指定できます。ビルド構成ファイルに代入値を指定する方法については、変数値の置換をご覧ください。

    • 承認(省略可): ビルドを実行する前に承認を必要とするチェックボックスをオンにします。

    • サービス アカウント: トリガーを呼び出すときに使用するサービス アカウントを選択します。サービス アカウントを選択しない場合は、デフォルトの Cloud Build サービス アカウントが使用されます。

  6. [作成] をクリックして、ビルドトリガーを保存します。

gcloud

ソースコードが Cloud Source Repositories にある場合にトリガーを作成するには:

    gcloud builds triggers create cloud-source-repositories \
    --repo=REPO_NAME \
    --branch-pattern=BRANCH_PATTERN \ # or --tag-pattern=TAG_PATTERN
    --build-config=BUILD_CONFIG_FILE \
    --service-account=SERVICE_ACCOUNT \
    --require-approval

ここで

  • REPO_NAME はリポジトリの名前です。
  • BRANCH_PATTERN は、ビルドを呼び出すリポジトリ内のブランチ名です。
  • TAG_PATTERN は、ビルドを呼び出すリポジトリ内のタグ名です。
  • BUILD_CONFIG_FILE はビルド構成ファイルのパスです。

  • SERVICE_ACCOUNT は、サービス アカウントに関連付けられたメールアドレスです。このフラグを含めない場合、デフォルトの Cloud Build サービス アカウントが使用されます。

  • (省略可)--require-approval は、承認を必要とするようにトリガーを構成するのに含めるフラグです。

フラグの一覧については、gcloud リファレンスで Cloud Source Repositories のトリガーを作成する方法をご覧ください。

ソースコードが GitHub にある場合にトリガーを作成するには:

    gcloud builds triggers create github \
    --region=REGION \
    --repo-name=REPO_NAME \
    --repo-owner=REPO_OWNER \
    --branch-pattern=BRANCH_PATTERN \ # or --tag-pattern=TAG_PATTERN
    --build-config=BUILD_CONFIG_FILE \
    --service-account=SERVICE_ACCOUNT \
    --require-approval
    --include-logs-with-status

ここで

  • REGION はトリガーのリージョンです。
  • REPO_NAME はリポジトリの名前です。
  • REPO_OWNER は、リポジトリ オーナーのユーザー名です。
  • BRANCH_PATTERN は、ビルドを呼び出すリポジトリ内のブランチ名です。
  • TAG_PATTERN は、ビルドを呼び出すリポジトリ内のタグ名です。
  • BUILD_CONFIG_FILE はビルド構成ファイルのパスです。
  • SERVICE_ACCOUNT は、サービス アカウントに関連付けられたメールアドレスです。このフラグを含めない場合、デフォルトの Cloud Build サービス アカウントが使用されます。
  • (省略可)--require-approval は、承認を必要とするようにトリガーを構成するのに含めるフラグです。
  • (省略可)--include-logs-with-status は、リポジトリのビルドログを表示するために指定できるフラグです。このフラグは、GitHub リポジトリと GitHub Enterprise リポジトリからのビルドでサポートされています。

フラグの一覧については、gcloud リファレンスで GitHub のトリガーを作成する方法をご覧ください。

Cloud Source Repositories または GitHub を使用して gcloud コマンドを実行してトリガーを作成すると、次のような出力が表示されます。

  NAME         CREATE_TIME                STATUS
  trigger-001  2019-10-30T20:45:03+00:00

ビルドトリガーをテストする

ビルドトリガーを手動でテストするには:

  1. Google Cloud Console で [トリガー] ページを開きます。

    [トリガー] ページを開く

  2. リストからトリガーを選択して、[トリガーを実行] をクリックします。

ビルドトリガーのスキップ

ソースコードを変更したときにビルドを実行したくない場合もあります。たとえば、ドキュメントや構成ファイルを更新したときに、ビルドを呼び出したくないことがあります。

このようなシナリオでは、[skip ci] または [ci skip] を commit メッセージに追加すると、ビルドは呼び出されません。

後の commit でビルドを実行する場合は、[トリガー] ページの [トリガーを実行] ボタンを使用します。

ビルドにリポジトリの履歴を含める

Git リポジトリでソースをビルドするために、Cloud Build はリポジトリのシャロー クローンを実行します。つまり、ビルドを開始した単一の commit だけが、ビルドするワークスペースにチェックアウトされます。Cloud Build は他のブランチや履歴をチェックアウトしません。これは効率と高めるために行われるため、ビルドで単一の commit をビルドするためにリポジトリ全体と履歴のフェッチを待機する必要はありません。

リポジトリの履歴を追加してビルドに含める場合は、ビルド構成ファイルにビルドステップを追加して、クローンの「シャローを解除」できます。例:

steps:
- name: gcr.io/cloud-builders/git
  args: ['fetch', '--unshallow']
...

git fetch の詳細については、git のリファレンスをご覧ください。ビルド構成ファイルの作成方法については、ビルド構成の概要をご覧ください。

承認のためにビルドを再送信する

ビルドが拒否された場合は、Google Cloud Console で以下の手順を行うことで、ビルドを再提出して承認を得ることができます。

  1. Google Cloud Console で Cloud Build 履歴 ページを開きます。

    Cloud Build 履歴ページを開く

  2. 承認を得るために再送信するビルドのビルド ID をクリックします。

  3. ページの上部にある [再ビルド] をクリックして、承認を得るビルドを再送信します。

権限のあるユーザーがビルドを承認すると、ビルドが開始されます。Cloud Build の承認の詳細については、承認のゲートビルドをご覧ください。

ビルドトリガーの更新

コンソール

  1. Google Cloud Console で [トリガー] ページを開きます。

    [ビルドトリガー] ページを開く

  2. ページの上部にあるプロジェクト セレクタのプルダウン メニューからプロジェクトを選択します。

  3. [開く] をクリックします。

  4. 更新するトリガーの行を探します。

  5. 行の右端にあるメニュー(丸が縦に並んだアイコン)をクリックします。

  6. [編集] を選択します。

gcloud

トリガーを更新するには:

  1. 更新するトリガーをエクスポートします。

     gcloud builds triggers export TRIGGER_NAME --destination=EXPORT_PATH
    

    ここで

    • TRIGGER_NAME はトリガーの名前です。
    • EXPORT_PATH は、トリガーをエクスポートする先のファイルパスです。たとえば、ファイルパスは examples/trigger.yaml として指定できます。トリガーのファイル名の拡張子は .yaml である必要があります。
  2. エクスポートしたトリガーを含むファイルを開きます。

    ファイルは次のようになります。

     createTime: '2022-05-26T21:56:11.830784153Z'
     filename: cloudbuild.yaml
     github:
       name: cloud-build-example
       owner: main
       push:
         branch: master
     id: 86201062-3b14-4b6a-a2fb-4ee924e8b1dd
     # remove field name and value to not show build logs
     includeBuildLogs: INCLUDE_BUILD_LOGS_WITH_STATUS
     name: trigger-001
    
  3. ファイルを手動で編集して、トリガーを更新します。

    トリガーに追加または削除するフィールドを表示するには、トリガー リソースをご覧ください。

  4. ファイルを保存します。

  5. トリガーをインポートします。

     gcloud builds triggers import --source=IMPORT_PATH
    

    ここで

    • IMPORT_PATH は、インポートするトリガーのファイルパスです。

これでビルドトリガーが更新されました。

ビルドトリガーを無効にする

コンソール

  1. Google Cloud Console で [トリガー] ページを開きます。

    [ビルドトリガー] ページを開く

  2. ページの上部にあるプロジェクト セレクタのプルダウン メニューからプロジェクトを選択します。

  3. [開く] をクリックします。

  4. 無効にするトリガーの行を見つけます。

  5. 行の右端にあるメニュー(丸が縦に並んだアイコン)をクリックします。

  6. [Disable] を選択します。

gcloud

トリガーを無効にするには:

  1. 無効にするトリガーをエクスポートします。

     gcloud builds triggers export TRIGGER_NAME --destination=EXPORT_PATH
    

    ここで

    • TRIGGER_NAME はトリガーの名前です。
    • EXPORT_PATH は、トリガーをエクスポートする先のファイルパスです。たとえば、ファイルパスは examples/trigger.yaml として指定できます。トリガーのファイル名の拡張子は .yaml である必要があります。
  2. エクスポートしたトリガーを含むファイルを開きます。

    ファイルは次のようになります。

     createTime: '2020-02-21T20:02:50.215599013Z'
     description: Push to any branch
     filename: cloudbuild.yaml
     github:
       name: example-repo-name
       owner: example-owner
       push:
         branch: .*
     id: example-id
     name: Push-to-any-branch
     tags:
     - github-default-push-trigger
    
  3. ファイルの末尾に disabled フィールドを追加し、値を True に設定します。

     disabled: True
    
  4. ファイルを保存します。

  5. トリガーをインポートします。

     gcloud builds triggers import --source=IMPORT_PATH
    

    ここで

    • IMPORT_PATH は、インポートするトリガーのファイルパスです。

これで、ビルドトリガーが無効になりました。

トリガーを無効にしても、トリガーは削除されません。トリガーを削除するには、ビルドトリガーを削除するをご覧ください。トリガーを再度有効にするには、ステータスを [有効] に変更します。

ビルドトリガーを削除する

コンソール

  1. Google Cloud Console で [トリガー] ページを開きます。

    [ビルドトリガー] ページを開く

  2. ページの上部にあるプロジェクト セレクタのプルダウン メニューからプロジェクトを選択します。

  3. [開く] をクリックします。

  4. 削除するトリガーの行を探します。

  5. 行の右端にあるメニュー(丸が縦に並んだアイコン)をクリックします。

  6. [削除] を選択します。

gcloud

トリガーを削除するには、次のコマンドを実行します。

  gcloud builds triggers delete TRIGGER_NAME

ここで

  • TRIGGER_NAME はトリガーの名前です。

フラグの一覧については、gcloud リファレンスでトリガーの削除方法をご覧ください。

ビルドトリガーのセキュリティへの影響

デフォルトでは、ビルドトリガーではビルドの実行に Cloud Build サービス アカウントが使用されます。これにより、トリガーを使用してビルドを実行するユーザーにビルド時間の権限が付与されます。ビルドトリガーを使用する場合は、次のセキュリティ上の影響に注意してください。

  • Cloud プロジェクトへのアクセス権はないが、プロジェクト内のビルドトリガーに関連付けられたリポジトリへの書き込みアクセス権があるユーザーは、ビルドされるコードを変更する権限を持ちます。
  • GitHub pull リクエスト トリガーを使用している場合は、リポジトリへの読み取りアクセス権を持つすべてのユーザーが pull リクエストを送信できます。これにより、pull リクエスト内のコードの変更を含むビルドが実行される可能性が生じます。GitHub pull リクエスト トリガーでこの動作を無効にする方法については、GitHub トリガーの作成をご覧ください。

トリガーに必要なロールのみを持つサービス アカウントを作成することをおすすめします。詳細については、ユーザー指定のサービス アカウントを構成するをご覧ください。Cloud Build サービス アカウントとそれに関連付けられた権限の詳細については、Cloud Build サービス アカウントをご覧ください。

次のステップ