次の方法で共有


パイプライン キャッシュ

Azure DevOps Services

パイプライン キャッシュを使用すると、以前の実行からダウンロードした依存関係を再利用してビルド時間を短縮できるため、同じファイルを再作成または再ダウンロードする必要がなくなります。 これは、各実行の開始時に同じ依存関係が繰り返しダウンロードされるシナリオで特に役立ちます。 これは、多くの場合、数百または数千のネットワーク呼び出しを伴う時間のかかるプロセスです。

キャッシュは、キャッシュの復元と保存に必要な時間が、ファイルの再生成にかかる時間よりも短い場合に最も効果的です。 ただし、キャッシュによってパフォーマンス上の利点が得られない場合があり、ビルド時間に悪影響を及ぼす可能性もあります。 キャッシュが適切なアプローチであるかどうかを判断するには、特定のシナリオを評価することが重要です。

手記

パイプライン キャッシュは、クラシック リリース パイプラインではサポートされていません。

パイプラインアーティファクトとパイプラインキャッシュを使用するタイミング

パイプラインキャッシュと パイプラインアーティファクト は同様の機能を実行しますが、さまざまなシナリオを対象としており、同じ意味で使用しないでください。

  • パイプライン成果物を使用: 1 つのジョブで生成された特定のファイルを利用し、それらを他のジョブと共有する必要がある場合(そうしないと、他のジョブが失敗する可能性があります)。

  • パイプライン キャッシュを使用する: 以前の実行のファイルを再利用してビルド時間を短縮する場合 (また、それらのファイルが含まれていない場合は、ジョブの実行機能に影響しません)。

手記

パイプライン キャッシュとパイプライン成果物は、すべてのレベル (無料および有料) で無料で利用できます。 詳細については、「アーティファクトのストレージ使用量」を参照してください。

セルフホステッド エージェントの要件

次の実行可能ファイルは、 PATH 環境変数に一覧表示されているフォルダーに配置する必要があります。 これらの要件は、セルフホステッド エージェントにのみ適用されることに注意してください。ホストされたエージェントには、必要なソフトウェアがプレインストールされています。

アーカイブ ソフトウェア/プラットフォーム ウィンドウズ Linux マック
GNUタール 必須 必須 いいえ
BSDタール いいえ いいえ 必須
7ジップ 推奨 いいえ いいえ

キャッシュ タスク: しくみ

キャッシュは、ジョブの セクションにstepsを追加することによってパイプラインに追加されます。

パイプラインの実行中に、キャッシュ ステップが検出されると、タスクは指定された入力に基づいてキャッシュの復元を試みます。 キャッシュが見つからない場合は、ステップが完了し、ジョブの次のステップが実行されます。

ジョブ内のすべてのステップが正常に実行されると、スキップされなかった "復元キャッシュ" ステップごとに、特別な "ジョブ後: キャッシュ" ステップが自動的に追加され、トリガーされます。 この手順はキャッシュを保存する の役割を担っています。

手記

キャッシュは不変です。 キャッシュが作成されると、そのコンテンツを変更することはできません。

キャッシュ タスクを構成する

キャッシュ タスクには、パスキーの 2 つの必須引数があります。

  1. path: キャッシュするフォルダーへのパス。 絶対パスまたは相対パスを指定できます。 相対パスは、$(System.DefaultWorkingDirectory)に対して解決されます。

    ヒント

    定義済みの変数を使用して、キャッシュするフォルダーへのパスを格納できます。 ただし、ワイルドカードはサポートされていません。

  2. key: 復元または保存するキャッシュの識別子を定義します。 キーは、文字列値、ファイル パス、またはファイル パターンの組み合わせで構成され、各セグメントは | 文字で区切られます。

    • 文字列:
      固定値 (キャッシュ名やツール名など)、または環境変数 (現在の OS やジョブ名など) から取得されます。

    • ファイル パス:
      コンテンツがハッシュされる特定のファイルへのパス。 このファイルは、タスクの実行時に存在する必要があります。 ファイル パスに似たセグメントはそのように扱われるので、特に .を含むセグメントを使用する場合は、"ファイルが存在しない" というエラーが発生する可能性があるため、注意が必要です。

      ヒント

      パスに似た文字列セグメントがファイル パスのように扱われないようにするには、二重引用符で囲みます (例: "my.key" | $(Agent.OS) | key.file

    • ファイル パターン:
      少なくとも 1 つのファイルと一致する必要がある glob スタイルのワイルドカード パターンのコンマ区切りのリスト。 例:

      • **/yarn.lock: ソース ディレクトリのすべての yarn.lock ファイル。
      • */asset.json, !bin/**: bin ディレクトリ内のファイルを除き、ソース ディレクトリの下のディレクトリにあるすべてのasset.jsonファイル。

ファイル パスまたはファイル パターンによって識別されるファイルの内容は、動的キャッシュ キーを生成するためにハッシュされます。 これは、キャッシュされている内容を一意に識別するファイルがプロジェクトにある場合に便利です。 たとえば、 package-lock.jsonyarn.lockGemfile.lockPipfile.lock などのファイルは、一意の依存関係のセットを表しているため、キャッシュ キーで参照されることがよくあります。 相対ファイル パスまたはパターンは、 $(System.DefaultWorkingDirectory)に対して解決されます。

  • 例の:

次の例は、Yarn パッケージをキャッシュする方法を示しています。

variables:
  YARN_CACHE_FOLDER: $(Pipeline.Workspace)/s/.yarn

steps:
- task: Cache@2
  inputs:
    key: '"yarn" | "$(Agent.OS)" | yarn.lock'
    restoreKeys: |
       "yarn" | "$(Agent.OS)"
       "yarn"
    path: $(YARN_CACHE_FOLDER)
  displayName: Cache Yarn packages

- script: yarn --frozen-lockfile

この例では、キャッシュ キーは 3 つの部分で構成されています。静的文字列 ("yarn")、ジョブが実行されている OS (キャッシュはオペレーティング システムごとに一意であるため)、 yarn.lock ファイルのハッシュ (依存関係を一意に識別するため)。

タスクが追加された後の最初の実行では、このキーによって識別されるキャッシュが存在しないため、キャッシュ ステップによって "キャッシュ ミス" が報告されます。 最後の手順の後、$(Pipeline.Workspace)/s/.yarn 内のファイルからキャッシュが作成され、アップロードされます。 次の実行では、キャッシュ ステップによって "キャッシュ ヒット" が報告され、キャッシュの内容がダウンロードされて復元されます。

checkout: selfを使用する場合、リポジトリは$(Pipeline.Workspace)/sにチェックアウトされ、.yarn フォルダーはリポジトリ自体に存在する可能性があります。

手記

Pipeline.Workspace は、すべてのディレクトリが作成されるパイプラインを実行しているエージェントのローカル パスです。 この変数の値は Agent.BuildDirectoryと同じです。 checkout: selfを使用していない場合は、リポジトリ内のYARN_CACHE_FOLDERの場所を指すように.yarn変数を更新してください。

復元キーを使用する

restoreKeys では、複数の正確なキーまたはキー プレフィックスに対してクエリを実行できます。 これは、指定した key がヒットしない場合にフォールバックとして使用されます。 復元キーは、プレフィックスでキーを検索し、最後に作成されたキャッシュ エントリを返します。 これは、パイプラインが完全に一致するものが見つからないが、それでも部分的なキャッシュヒットを使用する場合に役立ちます。

複数の復元キーを指定するには、それらを別々の行に一覧表示します。 復元キーが試行される順序は上から下になります。

  • 例の:

復元キーを使用して Yarn パッケージをキャッシュする方法の例を次に示します。

variables:
  YARN_CACHE_FOLDER: $(Pipeline.Workspace)/.yarn

steps:
- task: Cache@2
  inputs:
    key: '"yarn" | "$(Agent.OS)" | yarn.lock'
    restoreKeys: |
       yarn | "$(Agent.OS)"
       yarn
    path: $(YARN_CACHE_FOLDER)
  displayName: Cache Yarn packages

- script: yarn --frozen-lockfile

この例では、キャッシュ タスクは最初に指定したキーの復元を試みます。 キーがキャッシュに存在しない場合は、最初の復元キー ( yarn | $(Agent.OS)) が試行されます。 これにより、このプレフィックスと完全に一致するキャッシュ キーまたは先頭のキャッシュ キーが検索されます。

プレフィックスの一致は、 yarn.lock ファイルのハッシュが変更された場合に発生する可能性があります。 たとえば、キャッシュにキー yarn | $(Agent.OS) | old-yarn.lock (現在のold-yarn.lockとは異なるハッシュyarn.lock) が含まれている場合、この復元キーは部分的なキャッシュ ヒットになります。

最初の復元キーが一致しない場合、次の復元キー (yarn) yarnで始まるキャッシュ キーが検索されます。 プレフィックスの一致の場合、復元プロセスは最後に作成されたキャッシュ エントリを返します。

手記

パイプラインには複数のキャッシュ タスクを含めることができます。キャッシュのストレージ制限はありません。 同じパイプライン内のジョブとタスクは、同じキャッシュにアクセスして共有できます。

復元条件を使用する

一部のシナリオでは、キャッシュが正常に復元されたかどうかに基づいて、条件付きでステップを実行できます。 たとえば、キャッシュが復元された場合に依存関係をインストールする手順をスキップできます。 これは、 cacheHitVar 引数を使用して実現できます。

この入力を環境変数の名前に設定すると、キャッシュヒット時に変数が true に設定され、復元キーによって部分的なキャッシュ ヒットが発生した場合は inexact 、キャッシュが見つからない場合は false されます。 その後、 ステップ条件 またはスクリプト内でこの変数を参照できます。

キャッシュの復元時に install-deps.sh ステップがスキップされる例を次に示します。

steps:
- task: Cache@2
  inputs:
    key: mykey | mylockfile
    restoreKeys: mykey
    path: $(Pipeline.Workspace)/mycache
    cacheHitVar: CACHE_RESTORED

- script: install-deps.sh
  condition: ne(variables.CACHE_RESTORED, 'true')

- script: build.sh

キャッシュの分離とセキュリティ

異なるパイプラインと異なるブランチからのキャッシュ間の分離を確保するために、すべてのキャッシュは スコープと呼ばれる論理コンテナー内に格納されます。 スコープは、次を保証するセキュリティ境界として機能します。

  • あるパイプラインのジョブは、別のパイプラインのキャッシュにアクセスできません。

  • プル要求を作成するジョブは、(同じパイプラインの) ターゲット ブランチからキャッシュを読み取ることができますが、ターゲット ブランチのスコープ内でキャッシュを書き込む (作成) することはできません。

実行中にキャッシュ ステップが発生すると、キーによって識別されるキャッシュがサーバーから要求されます。 その後、サーバーはジョブに表示されるスコープからこのキーを持つキャッシュを検索し、キャッシュ (使用可能な場合) を返します。 キャッシュの保存時 (ジョブの最後) に、パイプラインとブランチを表すスコープにキャッシュが書き込まれます。

CI、手動、スケジュールされた実行

スコープ 既読 書き込み
ソース ブランチ はい はい
main ブランチ はい いいえ
master ブランチ はい いいえ

Pull request の実行

スコープ 既読 書き込み
ソース ブランチ はい いいえ
ターゲット ブランチ はい いいえ
中間分岐 (refs/pull/1/mergeなど) はい はい
main ブランチ はい いいえ
master ブランチ はい いいえ

Pull request fork の実行

ブランチ 既読 書き込み
ターゲット ブランチ はい いいえ
中間分岐 (refs/pull/1/mergeなど) はい はい
main ブランチ はい いいえ
master ブランチ はい いいえ

ヒント

キャッシュのスコープは既にプロジェクト、パイプライン、ブランチであるため、プロジェクト、パイプライン、またはブランチの識別子をキャッシュ キーに含める必要はありません。

例示

Bundler を使用する Ruby プロジェクトの場合は、 BUNDLE_PATH 環境変数をオーバーライドして、Bundler が Gem を検索する パス を設定します。

例の:

variables:
  BUNDLE_PATH: $(Pipeline.Workspace)/.bundle

steps:
- task: Cache@2
  displayName: Bundler caching
  inputs:
    key: 'gems | "$(Agent.OS)" | Gemfile.lock'
    path: $(BUNDLE_PATH)
    restoreKeys: | 
      gems | "$(Agent.OS)"
      gems   

既知の問題とフィードバック

パイプラインでのキャッシュの設定で問題が発生した場合は、 リポジトリでmicrosoft/azure-pipelines-tasksの一覧を確認してください。 問題が一覧に表示されない場合は、新しい問題を作成し、シナリオに関する必要な情報を提供してください。

Q&A(質疑応答)

Q: キャッシュをクリアできますか?

A: キャッシュのクリアはサポートされていません。 ただし、キャッシュ キーに文字列リテラル ( version2 など) を追加することで、既存のキャッシュでのヒットを回避できます。 たとえば、次のキャッシュ キーをこのキーから変更します。

key: 'yarn | "$(Agent.OS)" | yarn.lock'

これに対して:

key: 'version2 | yarn | "$(Agent.OS)" | yarn.lock'

Q: キャッシュの有効期限はいつですか?

A: キャッシュは、アクティビティがない状態が7日間続くと期限切れになります。

Q: キャッシュはいつアップロードされますか?

A: 指定した path からキャッシュが作成され、ジョブの最後のステップの後にアップロードされます。 詳細については、の例 を参照してください。

Q: キャッシュのサイズに制限はありますか。

A: 組織内の個々のキャッシュのサイズやキャッシュの合計サイズに対する制限は適用されません。