リポジトリのワークフローでのアクションの依存関係のロック

ワークフローが使用するすべてのアクションを検証済みコミットにピン留めするロックファイルを生成し、依存関係の変化に合わせて最新の状態に保ちます。

この機能を使用できるユーザーについて

People with write access to a repository

GitHub Enterprise Cloud

この記事で

ワークフローの依存関係をロックすると、参照するアクションに最初に確認されたものと同じコードが含まれていることが保証されます。 詳細については、「ワークフロー依存関係のロックファイル」を参照してください。

1. アクションの参照先を確認する

ロックファイルを作成すると、現在の分岐またはタグ参照に基づいて依存関係がコミットにピン留めされます。 固定したいバージョンがこれらのバージョンであることを確認します。

ワークフロー内の各 uses 参照が、サポートされている現在のバージョンのアクションを指していることを確認します。 ベスト プラクティスについては、セキュリティで保護された使用に関するリファレンス を参照してください。

ワークフローのいずれかが別のリポジトリで再利用可能なワークフローを呼び出す場合は、それらの参照も確認してください。 再利用可能なワークフローの依存関係は、あなたのロックファイルではなく、定義されているリポジトリのロックファイルによってカバーされます。 そのソース リポジトリには、完全なカバレッジを得るための独自のロックファイルが必要です。 組織が共有ワークフローを維持している場合は、まずそれらのリポジトリを追加してください。 「ワークフロー構成の再利用」を参照してください。

GitHub ActionsでDependabotの依存関係を管理することをお勧めします。 まだ有効になっていない場合は、ロックファイルを作成する前に有効にします。 「Dependabot でアクションを最新に保つ」を参照してください。

2. actions-lock 拡張機能をインストールする

  1. GitHub CLI をインストールします。

  2. 拡張機能をインストールします。

Bash
gh extension install github/gh-actions-lock

ヒント

拡張機能を後で更新するには、gh extension upgrade gh-actions-lock を実行してください。

3. ロックファイルを生成する

リポジトリのルートから、引数なしで拡張機能を実行します。 .github/workflows/下のすべてのワークフローがスキャンされ、解決可能な各アクションがコミット SHA にピン留めされ、ロックファイルが書き込まれます。

Bash
gh actions-lock

ディレクトリ全体ではなく 1 つのワークフローをオンボードするには、そのパスを渡します。

Bash
gh actions-lock .github/workflows/ci.yml

拡張機能は、ローカル パス操作 (uses: ./…) に従ったりロックしたりすることはありません。 ./ パスはランナーのワークスペースでチェックアウトされているものを実行するため、拡張機能でピン留めしたり、何を使用しているかを確認したりすることはできません。 $/ のパスは、ワークフローのコミット時にリポジトリ独自のアクションを実行するため、固定され、そのアクションが使用する action も固定できます。 2 つの比較については、 GitHub Actions　のワークフロー構文 を参照してください。

チェックアウト内のローカル アクションが他のアクションを使用している場合、これらのアクションはロックファイル エントリなしでは実行時に失敗するため、拡張機能は local-action エラーを報告し、何も書き込みません。 ローカル アクションを同一リポジトリ参照としてロックするには、次のコマンドを実行します。

Bash
gh actions-lock --migrate-local-actions

./参照を保持し、代わりに警告として報告するには、--ignore-local-actionsを渡します。 ローカル パス アクションの保持を参照してください。

すべてのオプションを確認するには、gh actions-lock --help を実行します。 特定のエラーまたは警告に関するヘルプについては、gh-actions-lock のトラブルシューティング ガイドを参照してください。

ローカル パス アクションの保持

--ignore-local-actions を渡した場合、実行時に何が起こるかは、ローカル アクションで使用されるアクションによって異なります。

  • 他のアクションは使用されません。たとえば run: ステップのみです。ワークフローは正常に実行されます。
  • 同じワークフローに対するロックファイル エントリがあるアクションを使用している場合: ワークフローは通常どおり実行されます。
  • そのワークフロー用のロックファイル エントリがないアクションを使用します: ジョブは、ローカル アクションのステップに達すると失敗し、lockfile missing pin for octo-org/setup-tool@v2.0.0などのエラーが発生します。 以前の手順は既に実行されています。

代わりに --migrate-local-actions すると、アクションはピン留めされた $/ 参照として実行されるため、それをお勧めします。 ./参照を保持する必要がある場合は、ローカル アクションが使用するアクションのワークフロー ロックファイル エントリを含めます。 同じ参照を持つ同じアクションを使用する複合アクションを追加し、実行されないステップでワークフローから呼び出します。 次に、 gh actions-lock --ignore-local-actionsを実行します。

# .github/actions/lock-local-deps/action.yml
name: Lock local action dependencies
description: Never runs. Lists the actions that ./.github/actions/build uses.
runs:
  using: composite
  steps:
    - uses: octo-org/setup-tool@v2.0.0

# In the workflow
steps:
  - uses: actions/checkout@v6
  - if: false
    uses: $/.github/actions/lock-local-deps
  - uses: ./.github/actions/build

エントリは、同じワークフローに対して記録される必要があります。 別のワークフローに対してのみ記録されたエントリはカウントされません。 ローカル アクションの依存関係が変更されたら、複合アクションを更新し、gh actions-lock --ignore-local-actions をもう一度実行してください。

4. 変更を確認してコミットする

拡張機能はロックファイルだけでなく他のファイルも変更するため、コミットする前に完全な差分を確認してください。 また、ワークフロー内の参照 uses も、解決された特定のバージョンに書き換えるので、octo-org/deploy-action@v3 などの参照が octo-org/deploy-action@v3.1.0 になる可能性があります。 これにより、解決先のコミットを変更することなく、参照がより具体的になります。

重要

リポジトリ、組織、または企業が指定したアクションのみを許可する場合は、コミットする前に許可リストを確認してください。 ワークフローがオンボードされると、タグは別のコードに移動できますが、ロックされた SHA は移動できないため、許可リストはタグではなくロックされたコミット SHA に対してチェックされます。 actions/checkout@v6などのタグにピン留めされたエントリは、ワークフローが導入されると一致しなくなります。 代わりにワイルドカードまたは完全コミット SHA を使用してください。 「リポジトリのGitHub Actions設定の管理」を参照してください。

--migrate-local-actions を渡した場合、拡張機能は、ワークフローとリポジトリの uses: $/… ファイル内で、独自のリポジトリ内のアクションへの参照も action.yml から uses: ./… に書き換えます。 この処理は、2 つのフォームの動作が異なるため、オプションを渡した場合にのみ実行されます。 ./ パスはランナーのワークスペース内にあるものに対して解決されますが、$/…参照は常にワークフローのコミットで実行されるため、ロックファイル エントリは必要ありません。 書き換えられた各行を確認してください。

5. ロックファイルを最新の状態に保つ

リポジトリのワークフロー ファイルとセキュリティ更新プログラムを使用して、ロックファイルを最新の状態に保ちます。

  1. 依存関係を変更したら拡張機能を再実行してください。 uses依存関係を持つワークフローを追加したり、既存のワークフローで gh actions-lock 依存関係を追加または削除したりするたびに、uses をもう一度実行します。

  2. バージョン更新は Dependabot に任せます。 Dependabotが、あなたが有効化したワークフロー内のアクションのバージョン更新を開くと、同じプルリクエストで対応するロックファイル エントリも再生成されます。 ワークフロー ファイルとロックファイルを不一致の状態にできません。

Dependabot は、既にオンボードされているワークフローのロックファイル エントリのみを更新します。 ロックファイルに含まれていないワークフロー内のアクションが更新対象になった場合、ワークフロー ファイルは通常どおり更新され、ロックファイルは変更されません。

  1. 移動した参照を再解決します。 移動された参照を拡張機能が処理する方法は、参照によって異なります。

    • ブランチまたは部分的なバージョン（main や v3 など）はロックされたコミットを保持し、拡張機能は ref-moved 警告を報告します。 これを進めるために、アップストリーム履歴を確認してから、gh actions-lock --relock を実行します。
    • v3.1.0は、ロックされたコミットを指している必要があります。 タグが移動した場合、拡張機能は、gh actions-lock --relock を実行するか、uses: 行を変更するまでエラーを報告します。
    • たとえば強制プッシュ後に、ロックされたコミットが参照の履歴に含まれなくなった書き換えられた履歴は、--relockでは修正されないエラーです。 アップストリームの履歴を確認したら、gh actions-lock --accept-movedを実行してください。 自動化で --accept-moved を使用しないでください。

ロックファイルの変更を確認

他の依存関係の変更と同様に、ロックファイルの変更を確認します。

  • 変更内容 commit は、ワークフローで実行されるコードです。 他の依存関係のバージョン更新と同じように扱います。
  • 変更された owner_id または repo_id 項目 はまれです。 つまり、その名前の背後にあるリポジトリは最初にロックしたリポジトリではないため、マージする前に調査してください。

ロックファイルが間違っているように見える場合は、ワークフロー ファイルを修正し、ロックファイルを再生成してください。 ロックファイルを手動で編集しないでください。

次のステップ

リポジトリのロックファイルを生成したら、開発者がコマンドを実行することを覚えておく必要なく、それが確実に適用され、常に最新の状態に保たれるようにします。 「アクションの依存関係に対するロックファイルの強制」を参照してください。