メインコンテンツへスキップ
見出し画像

GitHub Actionsにロックファイル(actions.lock)が登場。gh actions-lockの使い方とSHA固定との違い

    2026年10月14日、GitHubはActionsの「ワークフロー依存ロックファイル(workflow dependency lockfiles)」を公開プレビューとして提供を始めました。npmの package-lock.json のように、ワークフローが使うアクションを特定のコミットに固定するための仕組みです。ファイルは .github/workflows/actions.lock で、GitHub CLIの拡張 gh actions-lock で作ります。

    この記事では、GitHubのChangelogと公式ドキュメント、拡張のREADMEをもとに、仕組み、導入手順、運用で気をつける点を整理します。内容は2026年10月15日時点のものです。公開プレビューのため、形式やコマンドは予告なく変わる可能性があります。最新は公式ドキュメントで確認してください。

    この記事が関係する人・関係しない人

    関係する人

    • GitHub Actions のワークフローで、uses: actions/checkout@v6 のように外部のアクションをタグやブランチで指定している人

    • github.com の GitHub Enterprise Cloud(データレジデンシー付きを含む)、Team、Free プランのリポジトリを使っている人(今回の公開プレビューの対象)

    • アクションを40文字のコミットSHAで固定して運用していて、その手間を減らしたい人

    • 組織・Enterprise の管理者で、ワークフローの依存の固定を全体で必須にしたい人(Require lockfile ポリシー)

    関係しない人

    • GitHub Enterprise Server を使っている人(今回の公開プレビューの対象プランに含まれていません)

    • ワークフローで uses: ./… のローカルのアクションだけを使っている人(公式ドキュメントでは、実行中のコミットを指すため、もともと固定されていてロックファイルのエントリは不要とされています)

    自分が当てはまるかの確認方法

    • リポジトリの .github/workflows/ にあるワークフローで、外部のアクションをタグやブランチで指定している uses: の行があるかを見る

    • すでにロックファイルを入れたリポジトリでは、gh actions-lock --verify で、ファイルを書き換えずにロックファイルが最新かを確かめられる

    何を防ぐための仕組みか

    ワークフローで uses: actions/checkout@v6 のようにタグやブランチを指定すると、実行されるコードはその時点でタグが指しているコミットになります。タグやブランチは後から動かせるので、レビューした時点とは違うコードが、リポジトリに何の変更もないまま実行される可能性があります。アクションのリポジトリが乗っ取られた場合や、タグが付け替えられた場合がこれに当たります。

    Tags and branches can move, so the code that runs is not guaranteed to be the code that the workflow author originally reviewed.

    訳: タグやブランチは動くことがあるため、実行されるコードが、ワークフローの作者がもともとレビューしたコードと同じである保証はありません。(GitHub Docs「Workflow dependency lockfiles」)

    ロックファイルを使うと、ワークフローの書き方(タグ指定)はそのままで、実際の実行はロックファイルに記録したコミットに固定されます。タグやブランチが動いても、ロックしたコミットが使われます。

    ただし、公式ドキュメントも強調しているとおり、ロックは「その依存が安全である」ことを保証しません。ロックする前に、依存しているアクションをレビューする必要があります。

    画像

    提供範囲

    • 状態: 公開プレビュー(2026年10月14日〜)

    • 対象プラン: GitHub Enterprise Cloud、GitHub Enterprise Cloud with data residency、Team、Free

    • GitHub Enterprise Server: gh actions-lock 拡張は非対応

    • 拡張はバージョン1.0未満で、ロックファイルの形式、フラグ、動作は予告なく変わる可能性がある

    GitHub Actions workflow dependency lockfiles are now in public preview for GitHub Enterprise Cloud, GitHub Enterprise Cloud with data residency, Team, and Free plans.

    訳: GitHub Actions のワークフロー依存ロックファイルは、GitHub Enterprise Cloud、データレジデンシー付きの GitHub Enterprise Cloud、Team、Free の各プランで公開プレビューになりました。(GitHub Changelog「GitHub Actions workflow lockfiles in public preview」)

    ロックファイルの中身

    公式ドキュメントに載っている例は次のような形です。機械生成のファイルで、手で編集しないことになっています。

    # This file is machine-generated by `gh actions-lock`.
    # Do not edit by hand; run `gh actions-lock` to update.
    version: 'v0.0.2'
    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
    • workflows: ロックの対象にした(オンボードした)ワークフローと、それが使う依存の対応

    • dependencies: 依存ごとの解決結果

    • ref: ワークフローで使っているタグやブランチ

    • commit: 実際に実行するコミット

    • owner_id / repo_id: アクションのリポジトリの数値ID。実行時にActionsが照合する

    owner_id と repo_id を持っているので、リポジトリ名の変更や移管で別のリポジトリにすり替わったケースも検出できます。

    どこまでロックされるか

    • 推移的な依存も含む: 使っているアクションの中で、さらに別のアクションを使っている場合も対象になる

    • 再利用ワークフローの依存は含まない: 呼び出した再利用ワークフローの中の依存は、そのワークフローを定義しているリポジトリのロックファイルが担当する。共有ワークフローのリポジトリを先にオンボードするのが推奨されている

    • オンボードしたワークフローは全依存が必要: 1つでもロックファイルにない依存があると、そのワークフローは要件を満たさない

    • ロックしたコミットの条件: アクションのリポジトリのいずれかのブランチに存在している必要がある

    なお、ロックファイルを使うリポジトリでは、ワークフローに40文字のコミットSHAを直接書いて固定する必要はなくなる、と公式ドキュメントに書かれています。

    画像

    For repositories that adopt a lockfile, SHA pinning within workflow files is no longer necessary.

    訳: ロックファイルを導入したリポジトリでは、ワークフローのファイルの中でSHAを固定する必要はなくなります。(GitHub Docs「Workflow dependency lockfiles」)

    導入手順

    1. 事前の準備

    • GitHub CLI(gh)を入れる

    • 各 uses が、サポートされている現行バージョンのアクションを指しているか確認する

    • ロックファイルを作る前に、GitHub Actions向けのDependabotを有効にしておく(公式の推奨)

    2. 拡張を入れる

    gh extension install github/gh-actions-lock
    
    # あとで更新するとき
    gh extension upgrade gh-actions-lock

    3. ロックファイルを作る

    リポジトリのルートで実行します。引数なしなら .github/workflows/ 以下のすべてのワークフローが対象です。1つずつ段階的に導入したい場合は、ワークフローのパスを指定します。

    # すべてのワークフロー
    gh actions-lock
    
    # 1つだけオンボードする
    gh actions-lock .github/workflows/ci.yml
    
    # オプション一覧
    gh actions-lock --help

    書き込みは「全部成功するか、何も変えないか」のどちらかです。直せないエラーが1つでもあると、ほかの正常なワークフローも含めて何も書き換えません。

    4. 差分をレビューしてコミットする

    ロックファイルだけでなく、差分全体を見ます。拡張はワークフロー側も書き換えるためです。

    • uses が解決済みのバージョンに書き換わる。例: octo-org/deploy-action@v3 → octo-org/deploy-action@v3.1.0

    • 同じリポジトリ内のアクション uses: ./… は uses: $/… に書き換わる(ワークフローと action.yml の両方)。$/… は実行中のコミットで解決されるので、ロックファイルのエントリは要らない。$/… に @ref を付けるとエラー

    • 書き換えたくない場合は --no-migrate-local-actions を付ける

    ローカルパスのアクションが解決できないワークフローは、スキップされることがあります。uses: ./… のパスは、ファイルのあるディレクトリではなく、リポジトリのルートから解決される点に注意します。

    画像

    導入後に見直す設定

    許可するアクションのリスト

    リポジトリや組織の設定で「許可するアクションと再利用ワークフロー」を指定している場合、actions/checkout@v6 のようなタグ指定のエントリは、ロックしたSHAと一致しなくなります。ワイルドカードか、フルのコミットSHAで書き直します。

    Dependabot

    オンボード済みのワークフローでアクションのバージョン更新が出ると、Dependabotは同じプルリクエストの中でロックファイルの該当エントリも作り直します。追加の設定は要りません。ただし、Dependabotはワークフローのオンボード自体はしません。ロックファイルにないワークフローの依存を上げようとした場合は、オンボードが必要だと報告します。

    ロックファイルを最新に保つ

    • uses を持つワークフローを追加したとき、既存のワークフローで uses を増やしたり減らしたりしたときは、gh actions-lock を実行し直す

    • 通常の実行では、まだロックファイルにない参照だけを解決する。一方で、ロック済みのピンは毎回再チェックされる(リネーム・移管されていないか、コミットが存在するか、フルバージョンのタグがまだそのコミットを指しているか)。チェックに失敗すると処理が止まる

    • すべてのワークフローを対象に実行すると、削除したワークフローのエントリと、使われなくなった依存も消える。パスを指定した実行では、対象外のエントリは消えない

    main や v3 のようなブランチ・部分バージョンの参照は、通常の実行では解決し直しません。タグが別のコミットを指すようになったと報告された場合は、まず上流の履歴を確認し、正当な移動なら次を実行します。

    # 正当に動いた参照を解決し直す
    gh actions-lock --relock
    
    # 元のコミットが到達できなくなった場合(force-pushや削除)に、新しいコミットを受け入れる
    gh actions-lock --relock --accept-moved

    ロックファイルの差分をレビューするときは、commit の変更は「実行されるコードが変わる」ことなので、通常のバージョンアップと同じようにレビューします。owner_id や repo_id が変わることはまれなので、変わっていたらマージ前に調べます。

    CIでの検証と、チームでの強制

    検証用のフラグ

    • gh actions-lock --verify: ファイルを書き換えずに検証する。ブランチや部分バージョンでロックしたコミットが、その参照の履歴にまだあるかも確かめる。CIではこちらを使う

    • gh actions-lock --verify-local: オフラインで動き、書き込まない。すべての参照にエントリがあるかだけを確認し、エントリが信頼できるかは確認しない

    公式の強制ガイドでは、プルリクエストで gh actions-lock --verify を実行し、ロックファイルが古ければエラーで終わるジョブを作って必須チェックにする構成が紹介されています。ロックファイルを自動更新するジョブを作る場合は contents: write の権限が必要で、ブランチ保護やルールセットでGitHub Actionsからのpushを許可しておく必要があります。手元では、pre-commitフックに gh actions-lock --verify-local --no-fix を入れる方法も案内されています。

    あわせて、CODEOWNERSで .github/workflows/actions.lock にレビュー担当を割り当て、コードオーナーの承認を必須にしておくと、ロックファイルの変更が素通りしにくくなります。

    Require lockfile ポリシー

    管理者は「Require lockfile」ポリシー(これもプレビュー)を、エンタープライズ・組織・リポジトリの単位で適用できます。対象のワークフローがアクションの依存を持っているのにロックファイルにオンボードされていない場合、そのワークフローの実行がブロックされます。

    • 対象は、ロックファイルを導入済みのリポジトリに絞る

    • 実行を止めずに影響を見る Evaluate モードは、GitHub Enterpriseでのみ使える

    • Active にするのは、対象のワークフローすべてでロックファイルを最新に保つ仕組み(Dependabot、CIの検証、更新ジョブ)が整ってから

    まとめ

    • ロックファイルは .github/workflows/actions.lock。gh extension install github/gh-actions-lock で拡張を入れ、gh actions-lock で作る

    • タグ指定のまま、実行はロックしたコミットに固定される。推移的な依存も対象で、ワークフローに直接SHAを書く必要はなくなる

    • 再利用ワークフローの依存は、定義元リポジトリのロックファイルが担当する

    • 差分全体(uses の書き換え、$/… への置き換え)と、許可リストのタグ指定を確認する

    • CIでは --verify、正当にタグが動いたら --relock。Dependabotはオンボード済みのワークフローのロックを自動で更新する

    • ロックは安全性の保証ではない。ロックする前に依存をレビューする

    公開プレビューのため、仕様は変わる可能性があります。導入前に公式ドキュメントで最新の内容を確認してください。

    関連記事

    出典:
    GitHub Changelog「GitHub Actions workflow lockfiles in public preview」(2026-10-14) https://github.blog/changelog/2026-10-14-github-actions-workflow-lockfiles-in-public-preview/
    GitHub Docs「Workflow dependency lockfiles」 https://docs.github.com/actions/concepts/security/workflow-dependency-lockfiles
    GitHub Docs「Locking action dependencies in a repository's workflows」 https://docs.github.com/en/actions/how-tos/secure-your-work/lock-workflow-dependencies
    GitHub Docs「Enforcing lockfiles for action dependencies」 https://docs.github.com/en/actions/how-tos/administer/enforce-workflow-lockfiles
    github/gh-actions-lock https://github.com/github/gh-actions-lock

    開発ツールの仕様変更・提供終了の情報を毎朝お届けしています。見逃したくない方は、フォローしてください。

     
     

    HARu

     
     
    バックエンドエンジニア。Claude・GitHub・ローカルLLMなど開発ツールの新機能や仕様変更を、公式ドキュメントをもとに日本語で整理しています。「自分に関係あるか」「何を直せばいいか」がすぐ分かる記事を毎朝更新。記事はClaudeと一緒に作っています。

    あなたへのおすすめ