Azure DevOps Services
パイプライン キャッシュを使用すると、以前の実行からダウンロードした依存関係を再利用してビルド時間を短縮できるため、同じファイルを再作成または再ダウンロードする必要がなくなります。 これは、各実行の開始時に同じ依存関係が繰り返しダウンロードされるシナリオで特に役立ちます。 これは、多くの場合、数百または数千のネットワーク呼び出しを伴う時間のかかるプロセスです。
キャッシュは、キャッシュの復元と保存に必要な時間が、ファイルの再生成にかかる時間よりも短い場合に最も効果的です。 ただし、キャッシュによってパフォーマンス上の利点が得られない場合があり、ビルド時間に悪影響を及ぼす可能性もあります。 キャッシュが適切なアプローチであるかどうかを判断するには、特定のシナリオを評価することが重要です。
手記
パイプライン キャッシュは、クラシック リリース パイプラインではサポートされていません。
パイプラインアーティファクトとパイプラインキャッシュを使用するタイミング
パイプラインキャッシュと パイプラインアーティファクト は同様の機能を実行しますが、さまざまなシナリオを対象としており、同じ意味で使用しないでください。
パイプライン成果物を使用: 1 つのジョブで生成された特定のファイルを利用し、それらを他のジョブと共有する必要がある場合(そうしないと、他のジョブが失敗する可能性があります)。
パイプライン キャッシュを使用する: 以前の実行のファイルを再利用してビルド時間を短縮する場合 (また、それらのファイルが含まれていない場合は、ジョブの実行機能に影響しません)。
手記
パイプライン キャッシュとパイプライン成果物は、すべてのレベル (無料および有料) で無料で利用できます。 詳細については、「アーティファクトのストレージ使用量」を参照してください。
セルフホステッド エージェントの要件
次の実行可能ファイルは、 PATH
環境変数に一覧表示されているフォルダーに配置する必要があります。 これらの要件は、セルフホステッド エージェントにのみ適用されることに注意してください。ホストされたエージェントには、必要なソフトウェアがプレインストールされています。
アーカイブ ソフトウェア/プラットフォーム | ウィンドウズ | Linux | マック |
---|---|---|---|
GNUタール | 必須 | 必須 | いいえ |
BSDタール | いいえ | いいえ | 必須 |
7ジップ | 推奨 | いいえ | いいえ |
キャッシュ タスク: しくみ
キャッシュは、ジョブの セクションにsteps
を追加することによってパイプラインに追加されます。
パイプラインの実行中に、キャッシュ ステップが検出されると、タスクは指定された入力に基づいてキャッシュの復元を試みます。 キャッシュが見つからない場合は、ステップが完了し、ジョブの次のステップが実行されます。
ジョブ内のすべてのステップが正常に実行されると、スキップされなかった "復元キャッシュ" ステップごとに、特別な "ジョブ後: キャッシュ" ステップが自動的に追加され、トリガーされます。 この手順はキャッシュを保存する
手記
キャッシュは不変です。 キャッシュが作成されると、そのコンテンツを変更することはできません。
キャッシュ タスクを構成する
キャッシュ タスクには、パスとキーの 2 つの必須引数があります。
path: キャッシュするフォルダーへのパス。 絶対パスまたは相対パスを指定できます。 相対パスは、
$(System.DefaultWorkingDirectory)
に対して解決されます。ヒント
定義済みの変数を使用して、キャッシュするフォルダーへのパスを格納できます。 ただし、ワイルドカードはサポートされていません。
key: 復元または保存するキャッシュの識別子を定義します。 キーは、文字列値、ファイル パス、またはファイル パターンの組み合わせで構成され、各セグメントは
|
文字で区切られます。文字列:
固定値 (キャッシュ名やツール名など)、または環境変数 (現在の OS やジョブ名など) から取得されます。ファイル パス:
コンテンツがハッシュされる特定のファイルへのパス。 このファイルは、タスクの実行時に存在する必要があります。 ファイル パスに似たセグメントはそのように扱われるので、特に.
を含むセグメントを使用する場合は、"ファイルが存在しない" というエラーが発生する可能性があるため、注意が必要です。ヒント
パスに似た文字列セグメントがファイル パスのように扱われないようにするには、二重引用符で囲みます (例:
"my.key" | $(Agent.OS) | key.file
ファイル パターン:
少なくとも 1 つのファイルと一致する必要がある glob スタイルのワイルドカード パターンのコンマ区切りのリスト。 例:-
**/yarn.lock
: ソース ディレクトリのすべての yarn.lock ファイル。 -
*/asset.json, !bin/**
: bin ディレクトリ内のファイルを除き、ソース ディレクトリの下のディレクトリにあるすべてのasset.jsonファイル。
-
ファイル パスまたはファイル パターンによって識別されるファイルの内容は、動的キャッシュ キーを生成するためにハッシュされます。 これは、キャッシュされている内容を一意に識別するファイルがプロジェクトにある場合に便利です。 たとえば、 package-lock.json
、 yarn.lock
、 Gemfile.lock
、 Pipfile.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: 組織内の個々のキャッシュのサイズやキャッシュの合計サイズに対する制限は適用されません。