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

レビューしたGitHub Actionsと、実行されたGitHub Actionsは同じか――依存関係を固定するWorkflow Lockfile

    PRで次の1行をレビューし、承認したとします。

    
    - uses: octo-org/deploy-action@v3
    
    

    数日後、workflowのYAMLは1文字も変わっていません。では、実行されるコードも同じでしょうか。

    答えは「同じとは限らない」です。v3のようなタグやmainのようなブランチは、後から別のコミットを指せます。レビュー時と実行時の間に参照先が動けば、リポジトリに差分がなくても、runnerが読むコードは変わります。

    2026年10月14日、GitHubはGitHub ActionsのWorkflow Dependency LockfileをPublic Previewとして公開しました。人に読みやすいタグやブランチをworkflowに残しながら、実行時にはlockfileに記録したコミットを使う仕組みです。

    これは単なる新しいセキュリティ機能ではありません。AIがworkflowを書く機会が増えるほど重要になる、「人がレビューしたもの」と「機械が実行するもの」を一致させる設計です。

    この記事では、Workflow Lockfileが何を解決し、SHA直書きと何が違い、企業のCI/CDへ入れるなら何をレビュー対象にすべきかを整理します。情報は2026年10月15日時点です。

    問題は、YAMLではなく「実行時に解決されるもの」にある

    GitHub Actionsのworkflowは宣言です。uses: owner/action@v3は「この名前と参照を使う」という意図を人に伝えます。

    しかし、runnerが必要とするのは最終的なコードです。実行時にはv3を具体的なコミットへ解決します。ここに時間差があります。

    
    レビュー時の宣言
    
      owner/action@v3
    
            ↓ 実行時に解決
    
    実際のコード
    
      owner/action@具体的なコミットSHA
    
    

    タグやブランチが動けば、同じ宣言から別のコードが選ばれます。上流が正当に更新した場合も、アカウント侵害などで不正に動かされた場合も、利用側のYAML差分だけでは見えません。

    GitHub公式も、タグやブランチはレビュー後に動き得るため、後の実行が異なるコードを実行する可能性を明示しています。

    ここで押さえたいのは、「YAMLを承認した」という事実だけでは、実行コードを承認したことにならない点です。

    Workflow Lockfileは、可読な参照と不変な実行物を分ける

    Workflow Dependency Lockfileは、.github/workflows/actions.lockに依存関係の解決結果を保存します。GitHub Docsの例では、少なくとも次の情報を持ちます。

    • ref:workflowに書いたタグやブランチ

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

    • owner_id、repo_id:参照元リポジトリの数値ID

    つまり、workflowには人が理解しやすい@v3.1.0を残し、lockfileには機械が厳密に実行すべきコミットと参照元の同一性を持たせます。

    この分離には3つの利点があります。

    1. workflowの意図を読みやすく保てる

    40文字のSHAだけが並ぶYAMLは、どのリリースを使う意図なのか分かりにくくなります。タグを残せれば、レビューでは「なぜv3.1.0へ上げるのか」を読みやすい形で議論できます。

    2. 実行コードをコミットへ固定できる

    lockfileへ参加させたworkflowでは、GitHub Actionsは記録済みコミットを使います。タグが後から動いても、lockfileが変わらない限り実行対象は変わりません。

    3. 直接依存だけでなく推移的依存を見える化できる

    自分のYAMLに書いたActionが、内部で別のActionを使うことがあります。lockfileはActionの推移的依存も記録対象にします。

    ただし、reusable workflowが内部で使う依存関係には境界があります。その依存はreusable workflowを定義するリポジトリ側のlockfileが担当します。「自分のlockfileだけで全世界の依存が固定される」わけではありません。

    SHA直書きが間違いになったわけではない

    GitHubは従来、第三者Actionを完全長のコミットSHAへ固定することを推奨してきました。これは今も有効な考え方です。

    Workflow Lockfileは、SHA固定を否定するのではなく、固定場所と運用を変えます。

    比較するときの6つの観点

    • 実行の固定:SHA直書きでもWorkflow Lockfileでも固定できる。

    • YAMLの可読性:SHA直書きはコメント等で補う必要がある。Workflow Lockfileならタグ/ブランチを残せる。

    • 推移的Action依存:SHA直書きでは手作業で見落としやすい。Workflow Lockfileでは記録対象になる。

    • リポジトリ同一性:SHA直書きは名前中心。Workflow Lockfileはowner_id/repo_idも記録する。

    • 更新差分:SHA直書きはYAMLのSHAが変わる。Workflow Lockfileは参照とlockfileを同じPRで確認する。

    • 現時点の成熟度:SHA直書きは確立済み。Workflow LockfileはPublic Previewで、ツールもpre-1.0である。

    すでに完全長SHA固定とDependabot更新が安定しているなら、すぐ全面移行する必要はありません。一方、タグの可読性を残したい、推移的依存まで棚卸ししたい、組織ポリシーでlockfileを要求したい場合は、検証価値があります。

    CI/CDでは「宣言・解決結果・実行証跡」を分ける

    Workflow Lockfileの本質を、特定機能の使い方ではなく設計原則として捉えると、CI/CDで管理すべき成果物は3つに分かれます。

    1. 宣言:何をしたいか

    workflow YAMLは、人が意図を読むための成果物です。

    • どのイベントで起動するか

    • どのAction/reusable workflowを使うか

    • どの権限・Secrets・Environmentが必要か

    • 何をテストし、何を配布するか

    2. 解決結果:何を実行するか

    lockfileは、可変参照を不変な実行対象へ束縛する成果物です。

    • 参照したタグ/ブランチ

    • 解決したコミット

    • 直接依存と推移的依存

    • 参照元リポジトリの同一性

    ここは人が全行を精読するより、生成と整合確認を機械へ任せ、差分の意味をレビューする方が向いています。

    3. 実行証跡:実際に何が起きたか

    lockfileがあっても、実行環境、権限、入力、外部サービスまで固定できるわけではありません。後から照合するには、少なくとも次を追える必要があります。

    • workflowとlockfileのコミット

    • 実行run IDと開始時刻

    • runner image/self-hosted runnerの識別情報

    • 使用したEnvironmentと承認

    • 付与されたGITHUB_TOKEN権限

    • 生成物とprovenance/attestation

    宣言だけ、lockfileだけ、ログだけでは不十分です。3つを同じ変更・実行単位で結び付けると、「承認した意図」「固定したコード」「実際の結果」を照合できます。

    AIがworkflowを編集するチームで確認したい6項目

    AIコーディングエージェントは、アプリコードだけでなくworkflowも変更します。変更量が増えたと断定する根拠はまだ十分ではありませんが、workflowが小さな差分で頻繁に保守されることは実証研究でも示されています。

    導入時は、次の6項目をPRテンプレートやチェックへ入れると実務で使いやすくなります。

    1. 新しい依存を追加した理由が書かれているか

    lockfileが固定するのは「選ばれた依存」です。その依存を採用すべきかまでは判定しません。GitHub公式も、lockingは依存自体の安全性を判断しないため、ロック前にレビューが必要と注意しています。

    AIが提案したActionだから、人気だから、公式Marketplaceにあるから、だけで承認しないようにします。

    2. workflowとlockfileが同じPRで変わっているか

    新しいuses:を追加したのにlockfileが変わらない場合、生成漏れか、対象workflowがonboardされていない可能性があります。

    逆にlockfileだけが大きく変わった場合は、--relock等で複数依存が再解決された可能性があります。意図した更新と偶発的な更新を分けます。

    3. 直接依存だけでなく推移的依存の差分を見たか

    トップレベルのAction名が同じでも、内部依存が変わることがあります。レビューでは「何行変わったか」より、実行される依存グラフのどこが変わったかを見ます。

    4. 移動した参照を無条件に受け入れていないか

    gh actions-lock --verifyは、ロック内容が現在の参照と整合するかを確認します。正当な移動を取り込む--relockと、疑わしい移動も受け入れる--accept-movedは意味が違います。

    後者を自動修復として常用すると、「なぜ参照が動いたか」を確認する機会を失います。

    5. lockfileの適用外を把握したか

    2026年10月15日時点で、この仕組みはPublic Previewです。gh-actions-lockはpre-1.0で、GitHub Enterprise Serverは未対応です。local-path actionsにも制約があります。

    さらに、lockfileはrunner image、コンテナイメージ、OSパッケージ、ダウンロードスクリプト、外部APIまで固定しません。「Actionをロックしたから再現可能」と言い切らないことが重要です。

    6. 誰が更新を承認し、いつ再評価するか決めたか

    固定すると、更新しないリスクが生まれます。Dependabotは、onboard済みworkflowのAction参照を更新するとき、対応するlockfileエントリも同じPRで再生成できます。

    ただし、PRが自動で作られることと、自動でマージしてよいことは別です。重大度、利用権限、変更範囲、テスト結果に応じて承認者を決めます。

    小さく試すなら、1本のworkflowから始める

    Public Previewを企業で試すなら、最初から全workflowへ強制するより、権限と影響が読みやすい1本を選ぶ方が安全です。

    1. 外部Actionを使うが、本番デプロイ権限は持たないworkflowを選ぶ

    2. gh extension install github/gh-actions-lockで拡張を導入する

    3. 対象workflowをonboardし、actions.lockを生成する

    4. workflowとlockfileの差分を同じPRでレビューする

    5. CIでgh actions-lock --verifyを実行する

    6. Dependabot更新PRでworkflow参照とlockfileが同期するか確かめる

    7. 失敗時の解除・ロールバック手順を記録する

    導入評価では、「攻撃を防いだ件数」だけをKPIにしない方がよいでしょう。平常時には観測できません。代わりに、次を測れます。

    • 未登録依存をCIで検出できた件数

    • lockfile不整合で停止した件数

    • 依存更新PRのレビュー時間

    • 移動した参照を調査できた割合

    • onboard済みworkflowの比率

    • 実行証跡から依存コミットを追跡できた割合

    lockfileは「安全の証明」ではなく、レビュー対象を固定する

    Workflow Lockfileを入れても、危険なActionを安全にはできません。過剰な権限、Secretsの扱い、危険なpull_request_target、可変なrunner image、外部から取得するスクリプトといった別の問題も残ります。

    それでも、lockfileには大きな意味があります。

    レビュー時に見た依存と、実行時に使う依存を同じものとして扱えるからです。CI/CDレビューの議論を、「YAMLに何と書いてあるか」から「どのコードを、どの権限で、どの証跡を残して動かすか」へ進められます。

    AIにworkflowを書かせるかどうかより先に、AIが選んだ依存を人が確認でき、確認した解決結果だけが実行される仕組みを作る。

    その境界を、YAMLの外にも持つことが大切です。


    参考資料

    次に読む

    大企業のAI開発で、権限・承認・証跡・設計文書をどう分けるかを、実務で再利用できる判断基準として継続して整理します。同じ論点を追いたい方は、次の記事も見逃さないようフォローしておいてください。

     
     
    ユーザー企業の立場から、生成AI活用、社内SE、システム企画・設計を考えます。AIエージェントの権限・検証・運用や設計情報の活かし方を、実務で使える判断基準として整理します。

    あなたへのおすすめ