ローカルビルドでのBazel向けbuild cacheの設定

Bitrise Build Cacheをローカルの Bazel ビルドにも使用できます。ローカルビルドは、CIビルドと同じキャッシュを読み取るため、CIがすでに実行したアクションを、お使いのマシンで再度実行する必要はありません。

Bitrise Build Cache CLIは、キャッシュフラグを~/.bazelrcに書き込むことで、この設定を行います。

手順を手動で進める代わりに、AIコーディングエージェントを使って設定することもできます。Getting started with AIを参照してください。

始める前にClick to copy link

次のものを用意してください。

お使いのマシン上の、Bazel 6 以降で動作する Bazel プロジェクト。この設定では Bazel の credential helper サポートを使用しますが、これより前のバージョンにはありません。
Build Cacheが有効になっているBitrise workspace。Build Cacheページで確認できます。
マシンがVPN、ファイアウォール、または送信プロキシの内側にある場合は、Build Cacheが使用するBitriseホストへのネットワークアクセス。Network endpoints for firewalls and VPNsを参照してください。

アクティベートはプロジェクトごとではなくグローバルです

activate bazelは、ホームディレクトリの~/.bazelrcに単一のブロックを書き込みます。プロジェクトの.bazelrcには一切変更を加えません。

アクティベートを実行したプロジェクトだけでなく、お使いのマシン上のすべての Bazel プロジェクトがキャッシュフラグを使用します。ダッシュボードに報告されるリポジトリのURLは、アクティベートを実行したディレクトリの git リモートから読み取られるため、複数の Bazel プロジェクトがあるマシンでは、すべてが最初のプロジェクトとして報告されます。これはダッシュボードでの帰属にのみ影響し、キャッシュの正確性には影響しません。変更するには、別のプロジェクトのディレクトリでアクティベートを再実行してください。

CLIのインストールClick to copy link

Homebrew でCLIをインストールします(推奨)。

brew install bitrise-io/bitrise-build-cache/bitrise-build-cache

Homebrew を使用しない場合は、次のようにします。

curl --retry 5 -sSfL \
  'https://raw.githubusercontent.com/bitrise-io/bitrise-build-cache-cli/main/install/installer.sh' \
  | sh -s -- -b ~/.local/bin

インストール先がPATHに含まれていることを確認し、インストールを確認してください。

bitrise-build-cache --version

その後も、CLIをPATHに含めたままにしてください。Bazel は、セットアップ時だけでなく、ビルドのたびにCLIを実行して新しい認証トークンを取得します。

キャッシュのアクティベートClick to copy link

対話型ウィザードを実行します。

bitrise-build-cache activate --interactive

ウィザードでは、次の項目が求められます。

Sign in to Bitrise: 初回の実行時に、認証のためにブラウザーが開きます。CLIは認証情報をOSのキーチェーンに保存し、自動的に更新するため、2回目以降はこの手順をスキップします。使用可能なキーチェーンがないマシンでは、CLIは設定ファイルへの保存に切り替わります。
Select a workspace: 使用するBuild Cacheを持つworkspaceを選択します。アクセスできるものが1つだけの場合、CLIが自動的に選択します。
Which build tools should I set up: Bazelが選択されていることを確認してください。スペースキーでオプションを切り替え、Enter キーで確定します。
Cache for all projects, or only opted-in ones?: このマシンに複数のプロジェクトがあり、一部のプロジェクトだけでキャッシュを使用したい場合を除き、デフォルトの Always のままにします。Per-project cache scopingを参照してください。
Display name for this machine's local invocations: ローカルビルドがBuild Cacheダッシュボードに表示される名前です(例: local-<yourhandle>)。
Enable cache push: デフォルトの Yes, push too のままにします。Cache push modeを参照してください。

サインイン済みの場合の非対話型の同等のコマンドは、次のとおりです。

bitrise-build-cache activate bazel --cache

アクティベートが書き込む内容Click to copy link

~/.bazelrcの末尾に、マーカー付きのブロックが1つ追加されます。既存の内容は保持され、アクティベートを再実行した場合はこのブロックのみが更新されます。

# [start] generated-by-bitrise-build-cache
build --credential_helper=*.services.bitrise.io=bitrise-build-cache
build --remote_cache=grpcs://bitrise-accelerate.services.bitrise.io
build --remote_timeout=600s
build --remote_header=x-flare-buildtool=bazel
build --remote_header=x-flare-builduser=
build --remote_upload_local_results
build --bes_backend=grpcs://flare-bes.services.bitrise.io:443
build --bes_results_url=https://app.bitrise.io/build-cache/invocations/bazel/
build --bes_timeout=2m
build --bes_upload_mode=wait_for_upload_complete
build --build_event_publish_all_actions
build --show_timestamps
build --remote_header='x-org-id=<workspace-id>'
build --bes_header='x-org-id=<workspace-id>'
build --remote_header='x-repository-url=https://github.com/<org>/<repo>.git'
build --bes_header='x-repository-url=https://github.com/<org>/<repo>.git'
build --bes_header='x-os=<detailed OS info>'
build --bes_header='x-locale=C'
build --bes_header='x-default-charset=UTF-8'
build --bes_header='x-cpu-cores=4'
build --bes_header='x-mem-size=16759259136'
# [end] generated-by-bitrise-build-cache

特に注目すべき2行があります。

--credential_helperは、トークンを保存する代わりにCLIを指しています。そのため、Bazel はビルドのたびに新しいトークンを取得し、期限切れが近いログインでも動作し続けます。これが、CLIをPATHに含めておく必要がある理由です。
--remote_upload_local_resultsはプッシュモードで、デフォルトの設定です。--cache-push=falseを指定してアクティベートすると、代わりに--noremote_upload_local_resultsが書き込まれます。

x-os、x-cpu-cores、x-mem-size、x-locale、x-default-charsetの各ヘッダーはお使いのマシンの情報を表し、分析にのみ使用されます。cache keysには影響しません。これらはブロックを生成したマシンに固有であるため、設定をコミットする場合は注意が必要です。What is safe to commitを参照してください。

セットアップの確認Click to copy link

CLIのヘルスチェックを実行します。

bitrise-build-cache doctor

ローカル設定のすべての部分の状態が報告され、最後に総合的な判定が表示されます。他のビルドツール向けのプローブは、スキップとして報告されます。

Bitrise Build Cache - doctor
CLI version: 3.x.y

Healthy:
  ✓ auth                   OAuth login (keychain) (workspace <id>), token valid until <iso-timestamp>
  ✓ keychain-smoke         Set/Get/Delete round-trip OK
  ✓ auth-backend           latency <ms>, source=keychain, workspace=<id>
  ✓ project-scope          mode=always; cache_push=true (machine config); no .bitrise-build-cache.json found in <cwd> or parents.; would gate this directory: no
  ✓ xcelerate-proxy        skipped (xcode not activated)
  ✓ xcelerate-wrapper-path skipped (xcode not activated)
  ✓ xcelerate-enrichment   skipped (xcode not activated)
  ✓ ccache-helper          skipped (c++ not activated)
  ✓ ccache-binary          skipped (c++ not activated)
  ✓ log-dirs               no activated tool writes logs

Overall: ok

CLIが自動で修復できる問題を修復するには、bitrise-build-cache doctor --fix --interactiveを実行してください。

ビルドの実行Click to copy link

最初にbazel cleanを実行します。Bazel のローカルアクションキャッシュはリモートキャッシュの手前にあるため、ターゲットがすでにローカルでビルドされている場合、Bazel はディスクから結果を返し、Bitriseに接続しません。その結果、リモートキャッシュが動作している証拠は得られません。
```
cd path/to/your/bazel/project
bazel clean
```
ターゲットをビルドします。
```
bazel build //your/target:name
```

ウォームキャッシュにヒットしたビルドは、次のように終了します。

(16:47:35) INFO: Invocation ID: <invocation-id>
(16:47:35) INFO: Streaming build results to: https://app.bitrise.io/build-cache/invocations/bazel/<invocation-id>
(16:47:36) INFO: Analyzed target //src/close-matching-prs:close-matching-prs (91 packages loaded, 9216 targets configured).
(16:47:36) INFO: Found 1 target...
(16:47:36) INFO: Elapsed time: 0.934s, Critical Path: 0.18s
(16:47:36) INFO: 11 processes: 4 remote cache hit, 7 internal.
(16:47:36) INFO: Build completed successfully, 11 total actions

動作の確認Click to copy link

サマリー行が確認の根拠になります。次の3つのケースで表示が異なります。

サマリー行	意味
`11 processes: 4 remote cache hit, 7 internal.`	正常に動作しています。アクションはBitrise Build Cacheから取得されました。
`1 process: 4 action cache hit, 1 internal.`	ローカルキャッシュから返されました。リモートキャッシュには接続していないため、最初に`bazel clean`を実行してください。
`11 processes: 7 internal, 4 processwrapper-sandbox.`	ローカルで最初からビルドされました。このターゲットに対するキャッシュのエントリがないか、認証に失敗しています。出力の前のほうで`WARNING: Remote Cache: UNAUTHENTICATED`を探してください。

internalアクション(シンボリックリンクやファイルの書き込みなど)は、キャッシュできません。重要なのは、内部アクションを除いたアクションに対するリモートキャッシュヒットの比率です。

項目	確認場所	成功時の状態
`INFO: N processes: X remote cache hit`	Bazel のビルドサマリー	`bazel clean`後に、`remote cache hit`の数が0以外になる
`INFO: Streaming build results to:`	ビルドの最初と最後の行	呼び出しへのリンクが表示される
ダッシュボード	表示されたリンク、またはBuild Cacheページ	同じヒット数で、表示名の下に行が表示される

キャッシュプッシュモードClick to copy link

このガイドの設定では、キャッシュプッシュを有効にしてBuild Cacheをアクティベートします。ローカルビルドは共有キャッシュの読み取りと書き込みの両方を行います。お使いのマシンが実行したすべてのアクションは、チームメンバーやCIが再利用できるエントリになり、操作内容はBuild Cacheページに表示されます。

ローカルビルドでキャッシュの読み取りのみを行いたい場合は、以下のOpting into pull-only modeを参照してください。

プルのみモードの選択Click to copy link

チームがすでにCIからキャッシュを生成していて、ローカルビルドではキャッシュの読み取りのみを行いたい場合は、キャッシュプッシュをオフにします。ただしその場合、ローカルビルドはキャッシュに何も追加しません。そのため、CIがまだ実行されていないと、サマリー行には引き続き0 remote cache hitと表示されます。

bitrise-build-cache activate --interactiveを再実行し、キャッシュプッシュのプロンプトで No, pull only を選択するか、非対話型のアクティベートコマンドを実行します。

bitrise-build-cache activate bazel --cache --cache-push=false

ビルドを実行せずに、現在のモードを確認できます。

grep upload_local_results ~/.bazelrc
# --remote_upload_local_results    → push enabled (default)
# --noremote_upload_local_results  → pull-only

設定のリポジトリへのコミットClick to copy link

Bazel は、workspaceのルートにある.bazelrcをすでに読み取ります。そのため、キャッシュフラグをマシンごとに生成する代わりに、リポジトリにコミットできます。これにより、開発マシンのオンボーディングは、CLIのインストールとサインインだけで済みます。

brew install bitrise-io/bitrise-build-cache/bitrise-build-cache
bitrise-build-cache auth login

ファイルの組み合わせ方Click to copy link

Bazel は次の順序で設定ファイルを読み取り、単一値のフラグでは最後の値が優先されます。

システムファイル: /etc/bazel.bazelrc
workspaceファイル: <repo>/.bazelrc(コミットされたもの)
ホームファイル: ~/.bazelrc(アクティベートが実行された場合に書き込まれるもの)
コマンドラインフラグ

そのため、ホームファイルはコミットされたファイルより優先され、コマンドラインフラグはその両方より優先されます。Bazel が実際に読み込んだ内容を確認するには、ビルドに--announce_rcを追加します。

アクティベートを実行しない開発者にプルのみを強制するClick to copy link

CLIをインストールしてauth loginを実行するだけの開発者には、~/.bazelrcが作成されないため、コミットされたブロックを上書きするものがありません。CLIのデフォルトに関係なく、これらの開発者にキャッシュの読み取りのみを行わせたい場合は、プルのみのフラグをコミットします。

build --noremote_upload_local_results

CIでは、アクティベートを実行します。CLIはプッシュ有効のフラグを~/.bazelrcに書き込みます。ホームファイルはコミットされたworkspaceファイルより優先されるため、そのマシンに限り、コミットされたプルのみのフラグが上書きされます。

bitrise-build-cache activate bazel --cache

これにより、開発者ごとの設定なしで役割を分けられます。コミットされたファイルは、アクティベートを省略した開発者が引き継ぐプルのみのデフォルトとなり、キャッシュに書き込むべき環境がアクティベートを実行する環境となります。

コミットしても安全なものClick to copy link

行	コミット	理由
`--remote_cache`, `--remote_timeout`, `--bes_backend`, `--bes_results_url`, `--bes_timeout`, `--bes_upload_mode`, `--build_event_publish_all_actions`, `--show_timestamps`	はい	すべてのマシンで同一です
`--remote_header='x-org-id=…'` と対応する `--bes_header`	はい	Workspace全体で共通であり、マシン固有ではありません
`--remote_header='x-repository-url=…'` と対応する `--bes_header`	はい	このリポジトリを識別します
`--noremote_upload_local_results`	任意: アクティベートを省略する開発者にプルのみを強制したい場合	`auth login`のみを実行するすべての開発者に引き継がれます。CIでアクティベートを実行すると、`~/.bazelrc`に`--remote_upload_local_results`が書き込まれ、そのマシンではコミットされた値が上書きされます
`--credential_helper=*.services.bitrise.io=bitrise-build-cache`	はい(値を確認してから)	Bazel が`PATH`から検索する、バイナリ名のみの形式です。CLIが`PATH`に含まれていないマシンでアクティベートを実行した場合、CLIは代わりに絶対パスを書き込みます。その形式はコミットしないでください
`--bes_header='x-os=…'`, `x-cpu-cores`, `x-mem-size`, `x-locale`, `x-default-charset`	いいえ	マシンごとに異なり、`x-os`にはホスト名が含まれます。これらは分析にのみ使用され、cache keysには影響しませんが、コミットすると全員のビルドがお使いのマシンに帰属されてしまいます
`--remote_header=authorization="Bearer …"`	絶対にコミットしない	有効な認証情報です。CIで生成されたブロックにのみ表示されます

CLIがインストールされていない場合の動作Click to copy link

--credential_helperの行をコミットした場合、CLIをインストールしていないチームメンバーはビルドをまったく実行できません。Bazel はPATHからヘルパーを検索しますが見つからず、リモートキャッシュの初期化中に失敗します。

ERROR: Could not find file with name 'bitrise-build-cache' on PATH '...'
ERROR: Could not find file with name 'bitrise-build-cache' on PATH '...'
ERROR: Could not find file with name 'bitrise-build-cache' on PATH '...'
ERROR: Error initializing RemoteModule

Bazel はコード2で終了し、ターゲットはビルドされません。失敗はビルドの開始前に発生するため、ローカルビルドへのフォールバックはありません。

そのマシンにCLIをインストールしてbitrise-build-cache auth loginを実行すると、解決します。

リモートビルド実行Click to copy link

workspaceで Remote Build Execution が有効になっている場合は、アクティベートに--rbeフラグを追加することで、ローカルでも使用できます。その前に、workspace用のワーカーと、リポジトリの.bazelrcにあるプール設定を済ませておく必要があります。Remote Build Execution for Bazelを参照してください。

トラブルシューティングClick to copy link

まず、CLIのヘルスチェックから始めます。ローカル設定のすべての部分を検査し、自動で修復できる問題を修復します。

bitrise-build-cache doctor --fix --interactive

それでも問題が解決しない場合は、次の表を確認してください。

問題	対処
ウィザードがターミナルを必要とすると報告される	行ベースのモードにするには、`TERM=dumb bitrise-build-cache activate --interactive`を実行してください。
ビルドで`remote cache hit`ではなく`action cache hit`と報告される	Bazel がリモートキャッシュから取得するように、`bazel clean`を実行してください。
ビルドが`Could not find file with name 'bitrise-build-cache' on PATH`で失敗する	CLIがインストールされていないか、`PATH`に含まれていません。インストールしてから`bitrise-build-cache auth login`を実行してください。
認証情報の取得中にビルドが失敗し、credential helper の名前が表示される	CLIはインストールされていますが、認証情報がありません。`bitrise-build-cache auth login`を実行してください。
`doctor`が自動で修復できない問題を報告する	詳細なコンテキストを確認するには、`--debug`を付けて再実行してください。
ビルドがキャッシュに到達できない、またはキャッシュの呼び出しがタイムアウトする	VPN、ファイアウォール、またはプロキシがBitriseホストをブロックしている可能性があります。Network endpoints for firewalls and VPNsと照らし合わせて確認してください。

始める前にClick to copy link​

CLIのインストールClick to copy link​

キャッシュのアクティベートClick to copy link​

アクティベートが書き込む内容Click to copy link​

セットアップの確認Click to copy link​

ビルドの実行Click to copy link​

動作の確認Click to copy link​

キャッシュプッシュモードClick to copy link​

プルのみモードの選択Click to copy link​

設定のリポジトリへのコミットClick to copy link​

ファイルの組み合わせ方Click to copy link​

アクティベートを実行しない開発者にプルのみを強制するClick to copy link​

コミットしても安全なものClick to copy link​

CLIがインストールされていない場合の動作Click to copy link​

リモートビルド実行Click to copy link​

トラブルシューティングClick to copy link​

関連情報