GitHub Actions で Cargo と Rust のビルドをキャッシュする
最終更新
GitHub ActionsでCargoをキャッシュするには、最も簡単な方法はSwatinem/rust-cacheを使うことです。Cargoのレジストリ、gitの依存関係、target内のコンパイル済みの依存関係をキャッシュし、保存前にキャッシュを整理します。明示的なactions/cacheの形式も使えますが、targetを無条件にキャッシュすると、サイズが非常に大きくなり、処理も遅くなります。
方法1: Swatinem/rust-cache
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
- uses: dtolnay/rust-toolchain@stable
- uses: Swatinem/rust-cache@v2
- run: cargo test --locked
rust-cacheのREADME(2026年10月時点で確認)によると、このアクションは~/.cargo(インストール済みのバイナリ、レジストリのインデックスとクレートのキャッシュ、gitの依存関係。registry/srcは除く)と./targetをキャッシュします。自分のワークスペースのクレートはキャッシュせず、その依存関係のみをキャッシュします。キーは、ジョブ名、Rustのバージョン、Cargo.lockとマニフェストファイルのハッシュから作成され、CARGO_INCREMENTAL=0を設定します。
保存の前に、現在の依存関係ではないもの、インクリメンタルなアーティファクト、1週間より古いビルドアーティファクトを削除します。この整理処理こそ、手作業で書いたキャッシュよりも本アクションを選ぶ主な理由です。
実際によく使う入力項目:
- uses: Swatinem/rust-cache@v2
with:
workspaces: |
. -> target
tools/xtask -> target
shared-key: ci
save-if: ${{ github.ref == 'refs/heads/main' }}
cache-on-failure: true
workspacesは、Cargoのワークスペースを複数持つリポジトリ向けにworkspace -> targetのペアを指定します。shared-keyを指定すると、ジョブ名ごとにキャッシュを作る代わりに、複数のジョブでキャッシュを共有できます。check、clippy、testが同じ依存関係をビルドする場合に便利です。ただし、debugとreleaseのプロファイルは異なるため、同じプロファイルのジョブの間でのみ共有してください。save-ifを使うと、mainからのみ保存し、PRブランチによってクォータが消費されるのを防げます。cache-on-failureを使うと、ジョブが失敗しても保存します。テスト実行が失敗していても、依存関係はすでにコンパイル済みなので、有用です。
方法2: 明示的なactions/cache
- uses: actions/cache@v6
with:
path: |
~/.cargo/registry/index/
~/.cargo/registry/cache/
~/.cargo/git/db/
target/
key: cargo-${{ runner.os }}-${{ runner.arch }}-${{ hashFiles('**/Cargo.lock') }}
restore-keys: |
cargo-${{ runner.os }}-${{ runner.arch }}-
- run: cargo build --locked
これは、Cargo公式のガイダンスやactions/cacheの例で示されているパターンです。キーにはOS、アーキテクチャ、Cargo.lockを含めます。rust-toolchain.tomlでツールチェーンを固定していない場合は、コンパイラのバージョン(rustc --version)も追加してください。あるrustcでビルドしたアーティファクトは、別のrustcでは再利用できないためです。
キャッシュする対象と、しない対象
| パス | キャッシュするか | 理由 |
|---|---|---|
~/.cargo/registry/indexとregistry/cache | あり | クレートの再ダウンロードを避けられる |
~/.cargo/git/db | あり | gitの依存関係 |
~/.cargo/registry/src | なし | 展開済みのソース。Cargoはcacheから素早く再作成できる |
target/の依存関係 | あり | 最も効果が大きい。コンパイル済みの依存クレート |
自分のクレートのtarget/ | なし | コミットごとに変わり、キャッシュを肥大化させる |
target/**/incremental | なし | サイズが大きく、CIではほとんど役に立たない |
~/.cargo/bin | 注意が必要 | インストール済みツールは丸ごとではなく、バージョン単位でキャッシュする |
「ローリングキャッシュ」の落とし穴: Cargo.lockを明示的なキーに使うと、キャッシュが保存されるのはロックファイルが変わったときだけです。自分のワークスペースのクレートは保存されず、これは望ましい動作です。一方でgithub.shaをキーにすると、コミットごとにビルド出力がキャッシュに蓄積されていきます。rust-cacheは保存前に整理することで、これを避けています。
targetが大きすぎる場合
大規模なワークスペースのRustのtargetディレクトリは数GBに達することがあり、復元にかかる時間もそれに比例して増えます。対策として次の方法があります:
- CI向けにデバッグ情報を無効にする:
CARGO_PROFILE_DEV_DEBUG=0(またはdebug = "line-tables-only")。アーティファクトが小さくなり、リンクが速くなります。 targetをキャッシュする代わりに、GitHub Actionsのキャッシュバックエンドを持つsccacheをコンパイラのラッパーとして使う。ディレクトリ全体ではなく、クレート単位のコンパイル結果をキャッシュします。~/.cargoだけをキャッシュし、依存関係の再ビルドを許容する。多くの場合は遅くなりますが、クォータの消費は抑えられます。- より多くのコアで実行する。コンパイル時間はCPUに比例します。高速なランナーを参照してください。compiler.devでReact+Rust(Axum)とPostgresを測定した結果、CI全体の時間は2分37秒から1分45秒に短縮されました(ベンチマークを参照)。
キャッシュより効果の大きい高速化手法
cargo test --lockedはCargo.lockが古い場合に失敗するため、CI が依存関係を黙って解決することはありません。cargo nextestはバイナリをまたいでテストを並列実行します。大規模なテストスイートでは、テストシャーディングと組み合わせてください。- lint のみを行うジョブでは
cargo checkを使用してください。コード生成を省略します。 - 大きなバイナリでは、リンカーとして
moldまたはlldを使うとリンク時間を短縮できます。
キャッシュヒットの確認方法
- rust-cache は
Cache restored from key: ...をログに出力します(Restoring cacheと一致したキーを確認してください)。また、ポストステップでは保存した内容や保存されなかった理由の概要が表示されます。 - ビルド出力では、キャッシュが有効な実行では自分のクレートだけが
Compilingと表示されます。キャッシュがない実行では、すべての依存関係が表示されます。 - 同じ lockfile を使った実行同士で
cargo buildの所要時間を比較してください。 gh cache list --key rust --limit 20で、サイズと最終使用日時を確認できます。
よくある間違い
- 異なるジョブが 1 つのキーを奪い合う。 debug と release のビルド、または
clippyとtestは互いにキャッシュを無効化します。プロファイルごとにキーを分けてください。 --lockedを使わない。 lockfile が黙ってずれると、キーの意味が変わってしまいます。- すべての PR から
target全体をキャッシュする。 PR のキャッシュは PR 間で共有されないため、保存はmainから行ってください。詳しくは GitHub Actions でのキャッシュを参照してください。 - クォータの上限に達する。 Rust のキャッシュは大容量になりがちです。キャッシュの上限を確認してください。
よくある質問
target ディレクトリをキャッシュすべきですか?
依存関係の成果物はキャッシュしてください。自分のクレートの出力は、rust-cache のようなツールで削除させてください。すべてをキャッシュすると、際限なくサイズが増え続けます。
sccache は rust-cache より優れていますか?
両者は異なる問題を解決します。rust-cache はディレクトリを復元します。sccache は個々のコンパイル単位をキャッシュし、ブランチやプロファイルをまたいで機能します。大規模なワークスペースでは sccache が有利な場合があります。ほとんどのプロジェクトでは、rust-cache の方がシンプルです。
CARGO_INCREMENTAL=0 が重要な理由は何ですか?
インクリメンタルコンパイルは大きな成果物を書き出します。これはローカルでの再ビルドには役立ちますが、新規の CI マシンではほとんど役に立ちません。
cargo install のツールはどのようにキャッシュしますか?
ツール名とそのバージョンをキーにするか、taiki-e/install-action のようなビルド済みバイナリのアクションを使用してください。
次のステップ
関連記事: Rust CI をエンドツーエンドで高速化する方法、2 つのディレクトリを扱う同様のパターンとして Go modules のキャッシュ、そして GitHub Actions を高速化する方法。8 vCPU のマシンで Rust CI を試すには、compiler.dev の料金をご覧ください。
関連記事
- GitHub Actions で Go モジュールとビルドキャッシュをキャッシュするsetup-go または actions/cache を使用して、GitHub Actions で Go モジュール(GOMODCACHE)とビルドキャッシュ(GOCACHE)をキャッシュします。キー、go.sum、キャッシュヒットの確認方法を解説します。
- GitHub Actions で Gradle ビルドをキャッシュするgradle/actions/setup-gradle または actions/cache を使用して、GitHub Actions で Gradle の依存関係とビルドキャッシュをキャッシュします。キー、プルリクエストでの読み取り専用設定、クリーンアップ、確認方法を解説します。
- GitHub Actions で npm の依存関係をキャッシュするsetup-node または actions/cache を使用して、GitHub Actions で npm の依存関係をキャッシュします。動作する YAML、適切なキー、node_modules をキャッシュしない理由、キャッシュヒットの確認方法を解説します。
- GitHub Actionsでpipの依存関係をキャッシュするsetup-python または actions/cache を使って GitHub Actions で pip をキャッシュします。より高速な uv の選択肢もあります。キーの設計、キャッシュすべきでないもの、キャッシュヒットの確認方法を解説します。