ドキュメントには頻繁に更新が加えられ、その都度公開されています。本ページの翻訳はまだ未完成な部分があることをご了承ください。最新の情報については、英語のドキュメンテーションをご参照ください。本ページの翻訳に問題がある場合はこちらまでご連絡ください。

依存関係をキャッシュしてワークフローのスピードを上げる

ワークフローを高速化して効率を上げるために、依存関係や広く再利用されるファイルに対するキャッシュを作成して利用できます。

GitHub Actions is available with GitHub Free, GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub One. GitHub Actionsは、レガシーのリポジトリごとのプランを使っているアカウントが所有しているパブリックあるいはプライベートリポジトリでは利用できません。 詳しい情報については「GitHubの製品」を参照してください。

ここには以下の内容があります:

ワークフローの依存関係のキャッシングについて

ワークフローの実行は、しばしば他の実行と同じ出力あるいはダウンロードされた依存関係を再利用します。 たとえばMaven、Gradle、npm、Yarnといったパッケージ及び依存関係管理ツールは、ダウンロードされた依存関係のローカルキャッシュを保持します。

GitHubホストランナー上のジョブは、クリーンな仮想環境で開始され、依存関係を毎回ダウンロードしなければならず、ネットワークの利用率を増大させ、実行時間が長くなり、コストが高まってしまいます。 これらのファイルの再生成にかかる時間を短縮しやすくするために、GitHubはワークフロー内で頻繁に使われる依存関係をキャッシュできます。

ジョブのために依存関係をキャッシュするには、GitHubのcacheアクションを使わなければなりません。 このアクションは、ユニークなキーで指定されるキャッシュを取得します。 詳しい情報については「actions/cache」を参照してください。

警告: パブリックリポジトリのキャッシュには、センシティブな情報を保存しないことをおすすめします。 たとえばキャッシュパス内のファイルに保存されたアクセストークンあるいはログインクレデンシャルなどがセンシティブな情報です。 また、docker loginのようなコマンドラインインターフェース(CLI)プログラムは、アクセスクレデンシャルを設定ファイルに保存することがあります。 読み取りアクセスを持つ人は誰でも、リポジトリにプルリクエストを作成し、キャッシュの内容にアクセスできます。 リポジトリのフォークも、ベースブランチ上にプルリクエストを作成し、ベースブランチ上のキャッシュにアクセスできます。

成果物の比較と依存関係のキャッシング

成果物とキャッシングは、GitHubにファイルを保存できるようにするので似ていますが、それぞれの機能のユースケースは異なっており、入れ替えて使うことはできません。

  • キャッシングは、ジョブやワークフローの実行間で頻繁に変化しないファイルを再利用したいときに使ってください。
  • ジョブによって生成されたファイルをワークフローの終了後に見るために保存したい場合に成果物を使ってください。 詳しい情報については「成果物を利用してワークフローのデータを永続化する」を参照してください。

キャッシュへのアクセスについての制限

キャッシュにアクセスできるのは、push及びpull_requestイベントで起動されたワークフローからだけです。 詳しい情報については、「ワークフローをトリガーするイベント」を参照してください。

ワークフローは、現在のブランチ、baseブランチ(フォークされたリポジトリのbaseブランチを含む)、デフォルトブランチ(通常はmaster)で作成されたキャッシュにアクセスし、リストアできます。 たとえばデフォルトブランチのmasterで作成されたキャッシュは、どのプルリクエストからもアクセスできます。 また、feature-bブランチがfeature-aをbaseブランチとして持つなら、feature-bで起動されたワークフローはデフォルトブランチ(master)、feature-afeature-bで作成されたキャッシュにアクセスできます。

アクセス制限は、異なるワークフローとブランチ間の論理的な境界を作成することによって、キャッシュの分離とセキュリティを提供します。 たとえばfeature-aというブランチ(baseブランチはmaster)用に作成されたキャッシュは、feature-bというブランチ(baseブランチはmaster)へのプルリクエストからはアクセスできません。

cacheアクションの利用

cacheアクションは、提供されたkeyに基づいてキャッシュをリストアしようとします。 このアクションは、キャッシュを見つけるとそのキャッシュファイルを設定されたpathにリストアします。

正確なマッチがなければ、ジョブが成功したならこのアクションは新しいキャッシュエントリを作成します。 新しいキャッシュは提供されたkeyを使い、pathディレクトリ内にファイルを保存します。

既存のキャッシュにkeyがマッチしなかった場合に使われる、restore-keysのリストを提供することもできます。 restore-keysのリストは、 restore-keysが部分的にしかキャッシュキーとマッチしないために、他のブランチからのキャッシュをリストアする場合に役立ちます。 restore-keysのマッチに関する詳しい情報については「キャッシュキーのマッチ」を参照してください。

詳しい情報については「actions/cache」を参照してください。

cacheアクションの入力パラメータ

  • key: 必須 このキーはキャッシュの保存時に作成され、キャッシュの検索に使われます。 変数、コンテキスト値、静的な文字列、関数の任意の組み合わせが使えます。 キーの長さは最大で512文字であり、キーが最大長よりも長いとアクションは失敗します。
  • path: 必須 ランナーがキャッシュあるいはリストアをするファイルパス。 これには絶対パスあるいはワーキングディレクトリに対する相対パスが指定できます。 pathにはディレクトリを指定しなければなりません。 単一のファイルをキャッシュすることはできません。 pathは、GITHUB_WORKSPACEディレクトリの中になければなりません。 詳しい情報については、「環境変数の利用」を参照してください。
  • restore-keys: オプション keyに対するキャッシュヒットがなかった場合にキャッシュを見つけるために使われる代理キーの順序付きリスト。

cacheアクションの出力パラメータ

  • cache-hit: キャッシュがヒットした場合にtrue、キャッシュミスの場合にfalseに設定されます。

cacheアクションの使用例

以下の例では、package-lock.jsonファイル内のパッケージが変更された場合、あるいはランナーのオペレーティングシステムが変更された場合に新しいキャッシュが作成されます。 キャッシュキーはコンテキストと式を使い、ランナーのオペレーティングシステムとpackage-lock.jsonファイルのSHA-256ハッシュを含むキーを生成します。

name: Caching with npm

on: push

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v1

    - name: Cache node modules
      uses: actions/cache@v1
      with:
        path: ~/.npm # npm cache files are stored in `~/.npm` on Linux/macOS
        key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
        restore-keys: |
          ${{ runner.os }}-build-${{ env.cache-name }}-
          ${{ runner.os }}-build-
          ${{ runner.os }}-

    - name: Install Dependencies
      run: npm install

    - name: Build
      run: npm build

    - name: Test
      run: npm test

keyが既存のキャッシュにマッチした場合はキャッシュヒットと呼ばれ、このアクションはキャッシュされたファイルをpathディレクトリにリストアします。

keyが既存のキャッシュにマッチしなかった場合はキャッシュミスと呼ばれ、ジョブが成功して完了したなら新しいキャッシュが作成されます。 キャッシュミスが生じた場合、このアクションはrestore-keysと呼ばれる代理キーを検索します。

  1. restore-keysが渡された場合、cacheアクションはrestore-keysのリストにマッチするキャッシュを順番に検索します。

    • 完全なマッチがあった場合、アクションはそのファイルをpathディレクトリ中のキャッシュにリストアします。
    • 完全なマッチがなかった場合、アクションはリストアキーに対する部分一致を検索します。 アクションが部分一致を見つけた場合、最も最近のキャッシュがpathディレクトリにリストアされます。
  2. cacheアクションは完了し、ジョブ中のワークフローの次のステップが実行されます。
  3. ジョブが成功して完了したなら、アクションはpathディレクトリの内容で新しいキャッシュを作成します。

複数のディレクトリにファイルをキャッシュするには、各ディレクトリごとにcache アクションを使うステップが必要です。 キャッシュをいったん作成すると、既存のキャッシュの内容を変更することはできませんが、新しいキーで新しいキャッシュを作成することはできます。

コンテキストを使ったキャッシュキーの作成

キャッシュキーには、コンテキスト、関数、リテラル、GitHub Actionsがサポートする演算子を含めることができます。 詳しい情報については、「GitHub Actions のコンテキストと式構文」を参照してください。

式を使ってkeyを作成すれば、依存関係が変化したときに自動的に新しいキャッシュを作成できます。 たとえばnpmのpackage-lock.jsonファイルのハッシュを計算する式を使ってkeyを作成できます。

npm-${{ hashFiles('package-lock.json') }}

GitHubはhash "package-lock.json"という式を評価して、最終的なkeyを導出します。

npm-d5ea0750

キャッシュキーのマッチング

cacheアクションは最初に、ワークフローの実行を含むブランチ内でkeyrestore-keysのキャッシュヒットを検索します。 現在のブランチでヒットがなかった場合、cacheアクションは親及び上流のブランチでkey及びrestore-keysを検索します。

keyでキャッシュミスがあった場合に使うリストアキーのリストを提供できます。 特定の度合いが強いものから弱いものへ並べて複数のリストアキーを作成できます。 cacheアクションは順番にrestore-keysを検索していきます。 キーが直接マッチしなかった場合、アクションはリストアキーでプレフィックスされたキーを検索します。 リストアキーに対して複数の部分一致があった場合、アクションは最も最近に作成されたキャッシュを返します。

複数のリストアキーの利用例

restore-keys: |
  npm-foobar-${{ hashFiles('package-lock.json') }}
  npm-foobar-
  npm-

ランナーは式を評価します。この式は以下のようなrestore-keysになります。

restore-keys: |
  npm-foobar-d5ea0750
  npm-foobar-
  npm-

リストアキーのnpm-foobar-は、npm-foobar-という文字列で始まる任意のキーにマッチします。 たとえばnpm-foobar-fd3052denpm-foobar-a9b253ffというキーはいずれもこのリストアキーにマッチします。 最も最近の期日に作成されたキャッシュが使われます。 この例でのキーは、以下の順序で検索されます。

  1. npm-foobar-d5ea0750は特定のハッシュにマッチします。
  2. npm-foobar-npm-foobar-をプレフィックスとするキャッシュキーにマッチします。
  3. npm-npm-をプレフィックスとする任意のキーにマッチします。
検索の優先度の例
key:
  npm-feature-d5ea0750
restore-keys: |
  npm-feature-
  npm-

たとえばあるプルリクエストにfeatureブランチ(カレントスコープ)が含まれており、デフォルトブランチ(master)をターゲットにしている場合、アクションはkeyrestore-keysを以下の順序で検索します。

  1. featureブランチのスコープ内でnpm-feature-d5ea0750というキー
  2. featureブランチのスコープ内でnpm-feature-というキー
  3. featureブランチのスコープ内でnpm-というキー
  4. masterブランチのスコープ内でnpm-feature-d5ea0750というキー
  5. masterブランチのスコープ内でnpm-d5ea0750というキー
  6. masterブランチのスコープ内でnpmというキー

利用制限と退去のポリシー

GitHubは、7日間以上アクセスされていないキャッシュエントリを削除します。 以下の利用制限の範囲内であれば、好きなだけのキャッシュエントリを無料でリストアできます。

  • 400MBを超えないキャッシュ内の個々のファイル。 この制限を超えた場合、400 - Bad Requestが返されます。
  • リポジトリ内のすべてのキャッシュの合計サイズが2GBを超えない。 この制限を超えた場合、GitHubはキャッシュを保存しますが、合計サイズが2GB以下になるまでキャッシュを退去させはじめます。

担当者にお尋ねください

探しているものが見つからなかったでしょうか?

弊社にお問い合わせください