ワークフロー依存関係のロックファイル

ロックファイルは、ワークフローが依存するすべてのアクションを検証済みコミットにピン留めするため、確認したコードは実行されるコードです。

この記事で

ワークフローの依存関係をロックする理由

ワークフローは、多くの場合、 uses: octo-org/deploy-action@v3 や uses: octo-org/deploy-action@mainなど、タグまたは分岐によってアクションを参照します。 GitHub Actions は、実行時にタグまたはブランチが指すコミットへの参照を解決します。

タグとブランチは移動できます。 その結果、実行されるコードは、ワークフロー作成者が最初にレビューしたコードであるとは限りません。 アップストリームのメンテナのアカウントが侵害され、タグが再ポイントされると、リポジトリで悪意のあるコードが実行される可能性があります。

ワークフロー依存関係ロックファイルは、推移的な依存関係を含め、ワークフローが依存するすべてのアクションにコミット SHA をピン留めします。 再利用可能なワークフロー (jobs.<job_id>.uses) への呼び出しをピン留めしません。 再利用可能なワークフローをピン留めするには、完全なコミット SHA で参照します。 ロックファイルは、ランナーで実行されるアクション コードを制御します。 これは、入力パラメーター、シークレット、ランナーイメージなど、他のビルド入力を制御しません。 ロックファイルでは、対象となるアクション コードに対して次の内容が提供されます。

  • アクションの依存関係の再現可能な解決
  • レビュー可能な依存関係の変更と Dependabot バージョンの更新
  • CI/CD システムのアクション依存関係の監査可能なインベントリ

ロックファイルはどのように機能しますか？

ロックファイルは、.github/workflows/actions.lock にあるリポジトリで定義されます。 GitHub CLI拡張機能である gh actions-lock によって生成されるため、手動で編集してはいけません。

リポジトリのワークフローをロックファイルに 1 つずつ、またはまとめてオンボードできます。 ワークフローが追加された後:

  • ワークフローで使用されるすべてのアクションの依存関係は、ロックファイル内に存在する必要があります。
  • ロックされたコミットは、ワークフローの実行時に使われるコミットであり、許可されたアクション ポリシーが確認する対象です。
  • このコミットは、ロックファイルに記録された、そのアクション自身のリポジトリ内のブランチまたはタグから到達可能である必要があります。 フォークにのみ存在するコミット、またはその分岐またはタグから到達できなくなったコミットは、ワークフローの実行時に拒否されます。

ロックファイルは、再利用可能なワークフロー呼び出しの依存関係を_除き_、推移的な依存関係（あなたのアクションの依存関係が使用するアクション）を含む、独自のリポジトリ内のワークフローを対象とします。 再利用可能なワークフローは、独自のロックファイルを持つこともできます。 再利用可能なワークフローの依存関係は、それを呼び出すリポジトリのロックファイルではなく、定義されているリポジトリのロックファイルによってカバーされます。

ロックファイルは何を記録しますか?

ロックファイルには 2 つのセクションがあります。 workflows は、オンボードされた各ワークフローが使用する依存関係を記録し、dependencies はそれらの各参照が解決されるコミットを記録します。

# This file is machine-generated by `gh actions-lock`.
# Do not edit by hand; run `gh actions-lock` to update.
# Docs: https://gh.io/actions-lockfile
version: 'v0.0.3'
workflows:
    '.github/workflows/ci.yml':
        - 'octo-org/deploy-action@v3.1.0'
dependencies:
    'octo-org/deploy-action@v3.1.0':
        ref: 'v3.1.0'
        commit: 'sha1-...'
        owner_id: 44036562
        repo_id: 197814629

各依存関係には次が記録されます:

  • ref: コミットの解決元のタグまたはブランチ。
  • commit: 参照が解決された正確なコミット。 これは実行されるコードです。
  • owner_id と repo_id: ソース リポジトリの数値 ID。 GitHub Actions では、これらを使用して、実行時に、名前に対応するリポジトリが、まだロックしたものと同じであることを確認します。

この構造化形式は、YAML コメントをバージョン注釈として使用することなく、Dependabot などのツールが依存関係の更新を管理するために使用できる、機械可読なレコードを提供します。

ロックファイルと SHA ピン留めはどのように比較されますか?

GitHub では従来、ワークフロー ファイル内でサードパーティのアクションを完全な長さのコミット SHA にピン留めすることを推奨してきました。 ロックファイルを採用するリポジトリの場合、ワークフロー ファイル内での SHA ピン留めは 不要になります。 ロックファイルは、これが次のとおりであるため、より良いオプションです。

  • 推移的な依存関係をサポートします
  • ワークフロー ファイルを読みやすくする
  • ソース リポジトリの ID を記録します

また、ロックファイルは、それにオンボードされているワークフローに対する個別の アクションを完全長のコミット SHA に固定することを必須にする ポリシーも満たします。 「GitHub Actions ワークフローの実行の管理」を参照してください。

次のステップ

リポジトリのロックファイルを作成するには、 リポジトリのワークフローでのアクションの依存関係のロック を参照してください。