Google Cloud Buildとは｜料金・cloudbuild.yamlの書き方・トリガー設定【2026年版】

Cloud Buildは、Google Cloud上でビルド・テスト・デプロイを実行するフルマネージドのCI/CDサービスです。サーバーを1台も用意せず、リポジトリへのpushをきっかけにコンテナイメージを作り、Cloud RunやGKEへ届けるところまで自動化できます。一方で、2024年のデフォルトサービスアカウント変更、2025年3月のContainer Registry停止、2025年11月の料金改定と、ここ2年で前提が変わった点が多く、古い手順書のままではビルドが通りません。この記事では最初の1ビルドを通すまでの手順、cloudbuild.yamlの書き方、料金、そして権限まわりで実際に踏みやすい落とし穴を、公式ドキュメントの現行仕様に合わせて整理します。

まとめ

Cloud Buildの要点は5つです。無料枠は請求先アカウントごとに月2,500ビルド分（デフォルトプールのe2-standard-2）で、小規模チームなら実質無料で回せます。ビルド定義はcloudbuild.yamlにstepsを並べるだけ、1ステップ＝1コンテナ実行というシンプルな構造です。ソース連携はGitHubが実質の標準となり、Cloud Source Repositoriesは2024年6月17日から新規顧客に提供されていません。イメージのpush先はArtifact Registryで、Container Registryは2025年3月18日に書き込みが停止しました。そして最大のつまずきどころは料金でも構文でもなく、サービスアカウントとログ出力先の組み合わせです。以下、順に見ていきます。

Cloud Buildの実行モデル｜1ステップ＝1コンテナ

Cloud Buildは、指定したコンテナイメージを順番に実行する仕組みです。1つのビルドは複数のステップから成り、各ステップは「どのイメージで」「どのコマンドを」実行するかを指定するだけ。ステップ同士は/workspaceディレクトリを共有するため、前のステップが生成したファイルを次のステップがそのまま扱えます。

この単純さが、プラグイン依存のCIツールとの決定的な違いになります。ビルド環境はDockerイメージとして自分で決めるので、Node.js 22でもGo 1.24でも、必要なイメージをnameに書けばその瞬間から使えます。ビルドサーバーのメンテナンス、エージェントのバージョン管理、同時実行数のためのマシン増設といった運用作業はまるごと不要です。

典型的な使い方は、GitHubへのpushをトリガーにDockerイメージをビルドし、Artifact Registryへ格納し、Cloud RunやGKEへデプロイする流れ。テストの実行、Terraformの適用、静的解析も同じstepsの中に並べられます。

Cloud Buildの料金｜2025年11月にリージョン別価格へ改定

無料枠は月2,500ビルド分

Cloud Buildの課金単位はビルド分（build-minute）です。請求先アカウントごとに月2,500ビルド分が無料で、対象はデフォルトプールのe2-standard-2マシンタイプ。ビルドがキューで待っている時間は課金対象外で、実際に処理している秒数だけがカウントされます。なお公式はこの枠を「プロモーション枠であり変更されうる」と明記しているため、恒久的な保証ではない点は押さえておいてください。

1ビルド3分のパイプラインなら月833回まで無料枠に収まる計算で、数人のチームが1日20〜30回デプロイしても超えません。超えた瞬間に高額になるサービスでもないため、まず動かしてから最適化を考えて構いません。

2025年11月1日から地域別価格に

e2マシンタイプの新料金が2025年11月1日に発効し、それまでの全リージョン一律価格からリージョンごとの価格に変わりました。ビルドを実行するリージョンの選択が、そのままコストに効くようになったということです。

単価はリージョンで変わります。us-central1ではe2-highcpu-8とe2-highcpu-32が微減した一方、us-east1ではe2-mediumが$0.00339、e2-highcpu-32が$0.070512と上振れしました。同じマシンタイプでもリージョン間で1割以上の差が出るため、実際の単価は必ず公式の料金ページで確認してください。

マシンタイプを上げるべきかの判断

デフォルトプールで指定できるのはe2系4種類（e2-medium／e2-standard-2／e2-highcpu-8／e2-highcpu-32）で、既定はe2-standard-2です。n1-highcpu-8とn1-highcpu-32も指定できますが非推奨で、新規に選ぶ理由はありません。変更はgcloud builds submitの--machine-typeオプション、またはcloudbuild.yamlのoptions.machineTypeで行います。

ここで単価だけ見て「安いe2-mediumで」と選ぶと逆効果になります。請求額は所要時間×単価なので、8vCPUで所要時間が4分の1になるなら、単価が2.6倍でもトータルは安い。並列テストやマルチステージビルドのように並列度を上げられる処理ほど、上位マシンタイプが有利です。逆に、単一スレッドのコンパイルやネットワーク待ちが支配的なビルドでvCPUを増やしても、時間は縮まず請求だけ増えます。まず既定のe2-standard-2で計測し、CPU律速だと分かってから上げるのが正解です。

最初のビルドを通すまでの手順

APIの有効化とレジストリの準備

Google Cloudプロジェクトを用意したら、Cloud Build APIを有効化し、イメージの置き場所となるArtifact Registryのリポジトリを作ります。ここを飛ばすと最初のpushで必ず失敗します。

gcloud config set project YOUR_PROJECT_ID
gcloud services enable cloudbuild.googleapis.com artifactregistry.googleapis.com
gcloud artifacts repositories create my-repo \
  --repository-format=docker --location=asia-northeast1

APIを有効化した時点で、ビルドを実行するサービスアカウントが自動的に用意されます。どのサービスアカウントが使われるかはプロジェクトの作成時期によって変わり、これが後述の落とし穴に直結します。

ローカルからビルドを投げる

トリガーやリポジトリ連携を設定する前に、手元のソースを直接投げて動作を確認するのが早道です。カレントディレクトリの内容がアップロードされ、Cloud Build上でビルドが走ります。

gcloud builds submit --tag asia-northeast1-docker.pkg.dev/YOUR_PROJECT_ID/my-repo/my-app:v1 .

この1行で、Dockerfileを使ったイメージのビルドとArtifact Registryへのpushまで完了します。cloudbuild.yamlを使う場合は--configで指定し、--tagは省略してください。Dockerfileの書き方そのものに不安があるなら、Dockerfileの主要命令とベストプラクティスを先に押さえておくとビルド時間の短縮にも効きます。

cloudbuild.yamlの書き方

stepsの基本構文

ビルド定義はYAML（cloudbuild.yaml）またはJSON（cloudbuild.json）で書きます。機能差はなく、人が保守するならコメントを書けるYAML、ツールから自動生成するならJSONという使い分けです。テスト、イメージビルド、Cloud Runへのデプロイまでをつないだ最小構成は次のようになります。

steps:
  - name: 'node:22'
    entrypoint: 'npm'
    args: ['ci']
  - name: 'node:22'
    entrypoint: 'npm'
    args: ['test']
  - name: 'gcr.io/cloud-builders/docker'
    args: ['build', '-t', 'asia-northeast1-docker.pkg.dev/$PROJECT_ID/my-repo/my-app:$SHORT_SHA', '.']
  - name: 'gcr.io/cloud-builders/docker'
    args: ['push', 'asia-northeast1-docker.pkg.dev/$PROJECT_ID/my-repo/my-app:$SHORT_SHA']
  - name: 'gcr.io/google.com/cloudsdktool/cloud-sdk'
    entrypoint: 'gcloud'
    args: ['run', 'deploy', 'my-app',
           '--image', 'asia-northeast1-docker.pkg.dev/$PROJECT_ID/my-repo/my-app:$SHORT_SHA',
           '--region', 'asia-northeast1']
images:
  - 'asia-northeast1-docker.pkg.dev/$PROJECT_ID/my-repo/my-app:$SHORT_SHA'
options:
  machineType: 'E2_HIGHCPU_8'
timeout: '1200s'

nameは実行するビルダーイメージ、argsはそこへ渡す引数（1ステップ最大100個、1引数10,000文字まで）、entrypointはイメージ既定のエントリポイントを上書きするときに指定します。dirを書くと作業ディレクトリが/workspace/<dir>になり、モノレポで特定サブディレクトリだけビルドする場合に便利です。argsの代わりにscriptでシェルスクリプトを直接書くこともできますが、argsやentrypointとの併用はできません。

置換変数は手動実行だと空になる

$PROJECT_IDや$SHORT_SHAは組み込みの置換変数ですが、ここに罠があります。COMMIT_SHA・SHORT_SHA・BRANCH_NAMEなどはGitリポジトリのイベントから値が渡されるため、トリガー経由のビルドでしか設定されません。gcloud builds submitはソースをアーカイブとしてアップロードする方式なので、これらの変数はエラーにならず空文字に置換されます。上のyamlをそのまま手動実行すると、タグが空のmy-app:という不正なイメージ名になり、pushの段階で落ちます。

手動実行では値を明示的に渡してください。全ビルドで常に使えるのは$PROJECT_ID・$PROJECT_NUMBER・$BUILD_ID・$LOCATIONの4つだけです。

gcloud builds submit --config cloudbuild.yaml \
  --substitutions SHORT_SHA=$(git rev-parse --short HEAD)

timeoutとimagesの挙動

timeoutを省略した場合の既定値は60分、指定できる最大値は24時間です。ビルドが1時間ぴったりで強制終了する場合、原因はほぼこの既定値です。E2Eテストや大きなフロントエンドのビルドを含むパイプラインでは明示的に延ばしておきます。

imagesに書いたイメージは、全ステップが成功した後にCloud Buildが自動でpushします。ビルドして格納するだけならdocker pushのステップは不要で、途中のステップが落ちればpushも実行されないため、失敗したビルドのイメージがレジストリに残ることもありません。ただし上の例のように同一ビルド内でデプロイまで行う場合は話が別で、デプロイstepが動く時点ではまだ自動pushが走っていません。イメージが見つからず失敗するため、デプロイstepの前に明示的なdocker pushステップを挟む必要があります。push先は現在Artifact Registryです。Container Registryは2025年3月18日にシャットダウンされ書き込みができなくなりましたが、gcr.ioというホスト名自体はArtifact Registry上のgcr.ioリポジトリとして生きており、gcr.ioのURLのままpull／pushできます。上の例でgcr.io/cloud-builders/dockerを使えるのはこのためです（Google提供のビルダーイメージのため、シャットダウンの影響を受けません）。

APIキーやトークンはSecret Managerから渡す

プライベートリポジトリのトークンや外部APIキーをenvに平文で書くと、ビルドログとcloudbuild.yamlの両方に残ります。Secret Managerのシークレットを環境変数として注入する形にしてください。

availableSecrets:
  secretManager:
    - versionName: projects/$PROJECT_NUMBER/secrets/npm-token/versions/latest
      env: 'NPM_TOKEN'
steps:
  - name: 'node:22'
    entrypoint: 'bash'
    args: ['-c', 'npm config set //registry.npmjs.org/:_authToken=$$NPM_TOKEN && npm ci']
    secretEnv: ['NPM_TOKEN']

シークレット参照は通常の置換変数と区別するためドル記号を2つ重ねます（$$NPM_TOKEN）。ビルドを実行するサービスアカウントにはroles/secretmanager.secretAccessorが必要です。

ビルドを速くする｜キャッシュの効かせ方

Cloud Buildのビルドは毎回まっさらな環境で始まるため、何も設定しないとDockerのレイヤキャッシュがまったく効きません。マシンタイプを上げる前に、まずキャッシュを効かせるほうが費用対効果は高い。定番は、前回ビルドしたイメージをpullして--cache-fromに渡す方法です。

steps:
  - name: 'gcr.io/cloud-builders/docker'
    entrypoint: 'bash'
    args: ['-c', 'docker pull asia-northeast1-docker.pkg.dev/$PROJECT_ID/my-repo/my-app:latest || exit 0']
  - name: 'gcr.io/cloud-builders/docker'
    args: ['build', '-t', 'asia-northeast1-docker.pkg.dev/$PROJECT_ID/my-repo/my-app:latest',
           '--cache-from', 'asia-northeast1-docker.pkg.dev/$PROJECT_ID/my-repo/my-app:latest', '.']
images: ['asia-northeast1-docker.pkg.dev/$PROJECT_ID/my-repo/my-app:latest']

1つ目のステップで前回イメージを取得し（初回は存在しないのでexit 0で握りつぶす）、2つ目でそれをキャッシュ元に指定します。末尾のimagesが必須で、これが無いと:latestが一度もpushされず、次回以降のpullが永久に空振りします。依存関係のインストール層が変わっていなければ、その層はスキップされます。あわせて、Dockerfile側で依存ファイルのCOPYとソースのCOPYを分けておくことが前提になります。この分け方ができていないと--cache-fromを書いてもキャッシュはヒットしません。

GitHub連携とビルドトリガー

ビルドトリガーは、リポジトリのイベントを検知して自動でビルドを開始する仕組みです。ブランチへのpushで起動するトリガーはmainマージ後の本番デプロイ、プルリクエストで起動するトリガーはマージ前のテストという役割分担になります。作成時にはビルド設定ファイルのパスと対象ブランチの正規表現を指定し、モノレポなら変更ファイルのパスフィルタも足します。

gcloud builds triggers create github \
  --name=deploy-main \
  --repo-owner=YOUR_ORG --repo-name=YOUR_REPO \
  --branch-pattern='^main$' \
  --build-config=cloudbuild.yaml

この書式はGitHub Appで接続した第1世代のトリガー向けです。第2世代の接続では--repositoryにリポジトリのリソース名を渡し、--regionを指定します。

ソースの接続方法は変わりました。かつて定番だったCloud Source Repositories（Google Cloud内蔵のGitホスティング）は、2024年6月17日以降、それまで使っていなかった組織・プロジェクトでは利用できません。APIの有効化自体ができないため、新規構築では選択肢から外してください。既存ユーザーは引き続き使えますが、公式は販売終了（End of Sale）を明言しており、シャットダウン日は2026年7月時点で未発表（1年前に告知予定）です。現在の推奨はGitHubやGitLabをDeveloper Connect、またはCloud Build repositories（第2世代）で接続する方式で、第2世代の接続はコンソールを介さずAPIやTerraformから管理できます。GitLabを併用している場合の選定軸はGitHubとGitLabの違いを比較した記事にまとめています。

権限設計の落とし穴｜Cloud Buildで最も詰まる場所

デフォルトのサービスアカウントはプロジェクトによって違う

Cloud Buildのトラブルで最も多いのは、構文でも料金でもなく権限です。しかも厄介なことに、「どのサービスアカウントでビルドが動くか」がプロジェクトの作成時期で変わります。

2024年5〜6月にデフォルトの挙動が変更され、変更後に初回ビルドを実行したプロジェクトは、Compute Engineのデフォルトサービスアカウント（[email protected]）でビルドを実行します。変更前から使っているプロジェクトは、従来どおりレガシーのCloud Buildサービスアカウント（[email protected]）のままです。

ネット上の記事やチュートリアルは大半が後者を前提に書かれています。新しいプロジェクトでその手順どおりにレガシーSAへロールを付与しても、実際に使われるのは別のSAなので権限エラーは消えません。まずビルドログの冒頭に出るサービスアカウント名を確認し、そのSAに必要なロールを付けてください。Artifact Registryへpushするならroles/artifactregistry.writer、Cloud Runへデプロイするならroles/run.developerとデプロイ先SAへのroles/iam.serviceAccountUserが要ります（--allow-unauthenticatedのようにIAMポリシーを書き換えるオプションを使う場合はroles/run.adminが必要です）。

ユーザー指定SAに切り替えるとビルドが起動しなくなる

Compute Engineのデフォルトサービスアカウントは既定でプロジェクト編集者相当の権限を持つため、そのまま使うのは権限過多です。Googleもユーザー指定のサービスアカウントを推奨しています。ところが、ビルド専用SAを作ってserviceAccountに指定すると、今度はビルドが開始すらせず、APIが次のエラーを返します。

if 'build.service_account' is specified, the build must either
(a) specify 'build.logs_bucket',
(b) use the REGIONAL_USER_OWNED_BUCKET build.options.default_logs_bucket_behavior option,
or (c) use either CLOUD_LOGGING_ONLY / NONE logging options

ユーザー指定サービスアカウントを使うと、Cloud Buildが管理するデフォルトのログバケットへ書き込めなくなるためです。解決策は3つありますが、実務ではログをCloud Loggingへ寄せる方法が最も手間がかかりません。

serviceAccount: 'projects/$PROJECT_ID/serviceAccounts/my-build-sa@$PROJECT_ID.iam.gserviceaccount.com'
options:
  logging: CLOUD_LOGGING_ONLY

この場合、ビルド用SAにroles/logging.logWriterを付けておきます。ログをCloud Storageに残す運用ルールがあるならlogsBucketに自分で作ったバケットを指定してloggingをGCS_ONLYにし、そのバケットへの書き込み権限をSAに与えます。NONEは障害調査の手段を失うので選ぶべきではありません。SAの正体とログ出力先の制約、この2つを最初に押さえておけば初期トラブルはほぼ避けられます。

GitHub Actionsとの使い分け

両者は競合しますが、選定基準ははっきりしています。デプロイ先がCloud RunやGKEなどGoogle Cloudに閉じているなら、Cloud Buildが有利です。Workload Identity連携やOIDCの設定なしに、ビルドを実行するサービスアカウントの権限だけでGoogle CloudのAPIを直接叩けるからです。鍵を発行してGitHubのSecretsに置く必要がなく、権限管理がIAMに一本化されます。

一方、リポジトリがGitHubにあり、成果物がGoogle Cloud以外にも配られる（npm公開、複数クラウドへのデプロイ、リリースノート生成など）なら、GitHub Actionsのほうが素直です。マーケットプレイスのアクション資産が桁違いに多く、PRのチェック結果がGitHubのUIへ統合される利点も大きい。GitHub Actionsでビルドと自動テストを設定する方法と見比べたうえで、「テストとレビューはGitHub Actions、mainマージ後の本番デプロイだけCloud Build」という併用も現実的な解です。

Cloud Buildを選ぶべきでない場面もはっきりしています。複数OS・複数バージョンの組み合わせテスト（ビルドマトリクス）を大量に回したい場合、Cloud Buildにマトリクス機能はなく、組み合わせの数だけstepsを手で書き並べることになります。ここはGitHub ActionsやGitLab CIを使うほうが早い。もう1つ、ビルドからVPC内のプライベートリソース（プライベートIPのCloud SQLや限定公開GKEなど）へ接続したい場合も注意が必要です。デフォルトプールはGoogle管理のホスト環境で動くためユーザーVPCには到達できず、プライベートプールとVPCピアリングの構成が別途必要になります。

よくある質問

Cloud Buildの無料枠はどれくらいですか

請求先アカウントごとに月2,500ビルド分です。対象はデフォルトプールのe2-standard-2マシンタイプで、キュー待ち時間は課金されません。1ビルド3分なら月833回程度まで無料枠に収まります。ただし公式はプロモーション枠であり変更されうると明記しています。

cloudbuild.yamlとcloudbuild.jsonはどちらを使うべきですか

機能差はありません。人が書いて保守するならコメントを書けるYAML、他のツールから自動生成するならJSONという使い分けで十分です。既定のファイル名はcloudbuild.yamlで、gcloud builds submit --configで任意のパスを指定できます。

ビルドが60分で強制終了してしまいます

timeoutの既定値が60分のためです。cloudbuild.yamlのトップレベルにtimeout: '3600s'のように秒数で指定して延長してください。上限は24時間です。

gcloud builds submitで$SHORT_SHAが空になります

COMMIT_SHAやSHORT_SHAはトリガー経由のビルドでのみ設定される変数で、手動実行では空文字に置換されます。--substitutions SHORT_SHA=$(git rev-parse --short HEAD)のように明示的に渡してください。

Cloud Source Repositoriesは今から使えますか

2024年6月17日以降、それ以前にCloud Source Repositoriesを使っていなかった組織・プロジェクトでは利用できません（APIの有効化自体ができません）。GitHubやGitLabをDeveloper Connectまたは第2世代のリポジトリ接続でつなぐか、Secure Source Managerを検討してください。

Container Registry（gcr.io）にpushできなくなりました

Container Registryは2025年3月18日にシャットダウンされ、書き込みができません。Artifact Registryへ移行してください。Artifact Registry上にgcr.ioリポジトリを設定していれば、gcr.ioのURLのままpushでき、イメージはArtifact Registryに保存されます。

関連記事

• Dockerfileとは｜書き方・主要命令・ベストプラクティスを解説【2026年版】
• GitHub Actionsでビルド・自動テストを設定する方法｜CI/CDワークフローの作り方
• GitHubとGitLabの違いを比較｜CI/CD・セキュリティで選ぶ判断基準
• Dev Container（devcontainer）のメリットとは｜Dockerで開発環境を統一する仕組みと設定【2026年版】