コンテンツへスキップ

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に達することがあり、復元にかかる時間もそれに比例して増えます。対策として次の方法があります:

  1. CI向けにデバッグ情報を無効にする: CARGO_PROFILE_DEV_DEBUG=0(またはdebug = "line-tables-only")。アーティファクトが小さくなり、リンクが速くなります。
  2. targetをキャッシュする代わりに、GitHub Actionsのキャッシュバックエンドを持つsccacheをコンパイラのラッパーとして使う。ディレクトリ全体ではなく、クレート単位のコンパイル結果をキャッシュします。
  3. ~/.cargoだけをキャッシュし、依存関係の再ビルドを許容する。多くの場合は遅くなりますが、クォータの消費は抑えられます。
  4. より多くのコアで実行する。コンパイル時間は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 を使うとリンク時間を短縮できます。

キャッシュヒットの確認方法

  1. rust-cache は Cache restored from key: ... をログに出力します(Restoring cache と一致したキーを確認してください)。また、ポストステップでは保存した内容や保存されなかった理由の概要が表示されます。
  2. ビルド出力では、キャッシュが有効な実行では自分のクレートだけが Compiling と表示されます。キャッシュがない実行では、すべての依存関係が表示されます。
  3. 同じ lockfile を使った実行同士で cargo build の所要時間を比較してください。
  4. gh cache list --key rust --limit 20 で、サイズと最終使用日時を確認できます。

よくある間違い

  1. 異なるジョブが 1 つのキーを奪い合う。 debug と release のビルド、または clippy と test は互いにキャッシュを無効化します。プロファイルごとにキーを分けてください。
  2. --locked を使わない。 lockfile が黙ってずれると、キーの意味が変わってしまいます。
  3. すべての PR から target 全体をキャッシュする。 PR のキャッシュは PR 間で共有されないため、保存は main から行ってください。詳しくは GitHub Actions でのキャッシュを参照してください。
  4. クォータの上限に達する。 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 の料金をご覧ください。

このRustビルドをcompiler.devで実行 カード登録不要 · 200 無料分

無料で試す