2022-4-8

GitHubActionsのcacheを一部翻訳

Caching dependencies to speed up workflows - GitHub Docs

日本語でのいい感じの記事が見当たらなかったので、公式を翻訳することにした。DeepL使って翻訳して、わかりにくいとこを直した程度だけど。

`cache` アクションを使用する

cache アクションは、指定された key に紐づくキャッシュの復元を試みます。キャッシュが見つかると、アクションはキャッシュされたファイルを設定された path に復元します。

完全に一致するものがない場合、ジョブが正常に完了すると、アクションは自動的に新しいキャッシュを作成します。新しいキャッシュは指定された key を使用し、 path に指定されたファイルが含まれます。

オプションで、キーが既存のキャッシュと一致しない場合に使用する restore-keys を指定することができます。別のブランチから、 restore-keys と key が部分的に一致するキャッシュを復元する際に restore-keys は役立ちます。restore-keys のマッチングの詳細については、"キャッシュ・キーのマッチング"を参照してください。

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

key: 必須キャッシュを保存する際、及びキャッシュを検索する際に使用されます。変数、コンテキスト値、静的文字列、関数の任意の組み合わせが可能です。キーの最大長は512文字です。最大長を超えた場合アクションは失敗します。
path: 必須キャッシュに保存またはキャッシュから復元するランナー上のパス（複数可）。
- 1つのパスを指定することもできますし、複数のパスを別々の行に追加することもできます。例えば
```
- name: Cache Gradle packages
  uses: actions/cache@v3
  with:
    path: |
      ~/.gradle/caches
      ~/.gradle/wrapper
```
- ディレクトリまたは単一のファイルを指定でき、グロブパターンもサポートされています。
- 絶対パス、またはワークスペース・ディレクトリからの相対パスが指定できます。
restore-keys: 任意代替リストアキーを含む文字列で、それぞれ1行に1つ指定します。指定されたkeyに紐づくキャッシュが存在しない場合、これらのリストアキーがキャッシュの検索と復元に指定された順序で順次使用されます。例えば
```
restore-keys: |
  npm-feature-${{ hashFiles('package-lock.json') }}
  npm-feature-
  npm-
```

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

cache-hit: キーに完全一致するものが見つかったことを示すブーリアン値。

`cache` アクションの使用例

この例では、 package-lock.json ファイル内のパッケージが変更されたとき、またはランナーのOSが変更されたときに、新しいキャッシュが作成されます。キャッシュキーには、ランナーのOSと package-lock.json ファイルのSHA-256ハッシュを含むキーを生成するためにコンテキストと式を使用します。

name: Caching with npm
on: push
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

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

      - if: ${{ steps.cache-npm.outputs.cache-hit == false }}
        name: List the state of node modules
        continue-on-error: true
        run: npm list

      - name: Install dependencies
        run: npm install

      - name: Build
        run: npm build

      - name: Test
        run: npm test

keyが既存のキャッシュと一致した場合（キャッシュヒットと呼ばれています）、アクションはキャッシュされたファイルを path にリストアします。

キーが既存のキャッシュと一致しない場合（キャッシュミスと呼ばれています）、ジョブが正常に完了すると自動的に新しいキャッシュが作成される。

キャッシュミスが発生した場合、アクションは指定された restore-key にマッチするものを検索します。

restore-keys を指定されている場合、キャッシュアクションは restore-keys とマッチするキャッシュを順次検索します。

完全に一致する物がある場合は、アクションはpathにキャッシュ内のファイルを復元します。
完全に一致する物がない場合は、アクションはリストアキーの部分一致検索をします。部分一致が見つかった場合、最新のキャッシュがpathに復元されます。

cache アクションが完了し、ジョブの次のステップが実行されます。
ジョブが正常に完了した場合、アクションは自動的に path ディレクトリの内容で新しいキャッシュを作成します。

キャッシュのマッチング処理の詳細については、"キャッシュ・キーのマッチング"を参照してください。一度キャッシュを作成すると、既存のキャッシュの内容を変更することはできませんが、新しいキーで新しいキャッシュを作成することは可能です。

キャッシュキーの作成にコンテキストを使用する

キャッシュキーには、GitHub Actions がサポートするコンテキスト、関数、リテラル、演算子を含めることができます。詳しくは、"コンテキスト" と "式" をご覧ください。

式を使用してキーを作成することで、依存関係が変更されたときに自動的に新しいキャッシュを作成することができます。

例えば、npmのpackage-lock.jsonファイルのハッシュを計算する式を用いてキーを作成することができます。そうしておくと、package-lock.jsonファイルを構成する依存関係が変更されると、キャッシュのキーが変更され、新しいキャッシュが自動的に作成されるようになります。

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

GitHubは式 hash "package-lock.json" を評価し、最終的なキーを導出します。

npm-d5ea0750

`cache` アクションの出力を利用する

キャッシュアクションの出力を使って、キャッシュヒットとキャッシュミスのどちらを発生させたかに基づいて何かをすることができます。キャッシュミスがあった場合 (指定したキーに完全に一致するキャッシュが見つからなかった場合)、 cache-hit の出力は false に設定されます。

上記のワークフロー例では、キャッシュミスが発生した場合、ノードモジュールの状態をリストアップするステップがあります。

- if: ${{ steps.cache-npm.outputs.cache-hit == false }}
  name: List the state of node modules
  continue-on-error: true
  run: npm list

GitHubActionsのcacheを一部翻訳

cache アクションを使用する

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

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