テック技報最新号へ →
セキュリティ

GitHub Actions の依存を lockfile（actions.lock）で固定する

2026-10-28 に GA になった GitHub Actions のワークフロー lockfile を使うと、uses: は @v7.0.1 のような読める書き方のまま、実行するコミットを .github/workflows/actions.lock に記録したものへ固定できる。アクションの内部で呼ばれる別アクション（推移的依存）まで固定できるのが SHA 直書きとの大きな違い。

@poly_soft · 投稿 2026-10-28
#github-actions#supply-chain#pinning#lockfile#ci-cd

なぜ SHA 直書きだけでは足りないのか

  • @v7 や @v7.0.1 のタグ指定は、タグを force push で付け替えられると中身が変わる。2026 年 3 月の aquasecurity/trivy-action 侵害では、ほとんどのバージョンタグが書き換えられた。
  • 自分のワークフローで trivy-action@<SHA> と固定していても、trivy-action の中が uses: aquasecurity/[email protected] のようにタグ参照なら、そちらの改ざんで巻き込まれる。lockfile は内部の参照もたどってコミットを記録する。
  • これまでの SHA 固定（GitHub Actions の uses をコミット SHA で固定する（pinact））は、自分のワークフローに書いた直接の依存だけが対象だった。

導入手順

bash
gh extension install github/gh-actions-lock   # gh auth login 済みであること
gh actions-lock                               # .github/workflows/ 全体を対象に actions.lock を生成
gh actions-lock .github/workflows/ci.yml      # 1 本ずつ段階的に導入する場合
git add .github/workflows/
  • 拡張は lockfile だけでなくワークフローも書き換える（例: actions/checkout@v7 → @v7.0.1）。差分全体を見てからコミットする。
  • lockfile を作る時点のタグ・ブランチが指すコミットがそのまま固定される。固定する前に、その版で問題ないかを確認する（lockfile は依存が安全かどうかは判定しない）。
  • ワークフローに導入されると、実行ログに「Using locked action versions from the workflow's lockfile」と出る。

運用

コマンド用途
gh actions-lock導入・修正（書き込みあり）
gh actions-lock --relockmain や v4 など動く参照を、上流を確認したうえで進める
gh actions-lock --verifyCI 用。書き換えずに同じ検査（由来の検証を含む）
gh actions-lock --verify-localpre-commit 用。全 uses: に lockfile のエントリーがあるかだけ（由来は見ない）
gh actions-lock --no-fix読み取り専用のレポート
  • uses: を追加・削除したら gh actions-lock をやり直す。Dependabot は、導入済みワークフローのアクション更新 PR で lockfile の該当エントリーも同じ PR で作り直す。
  • 完全なバージョンタグ（v3.1.0）が別コミットへ動いた場合はエラーになる。履歴が書き換えられて固定したコミットが参照の履歴にない場合も、--relock では直らないエラー。こうした警告は「タグが付け替えられた」兆候として調べる。
  • 管理者は Require lockfile ポリシー（Enterprise・組織・リポジトリ）で導入を強制できる。対象リポジトリで lockfile を作って検証してから有効にしないと、準備前のリポジトリの実行が止まる。
  • 既存の「フル SHA 固定を必須にする」ポリシーと併用でき、lockfile に入っているワークフローは SHA 直書きなしで両方を通る。

注意点

  • 対象はステップの uses: だけ。ジョブ単位で他リポジトリの再利用ワークフロー（jobs.<id>.uses）を呼ぶ場合、その依存は呼び出し先リポジトリの lockfile で固定される。共有ワークフローのリポジトリから先に導入する。
  • ローカルの ./… アクションはたどられない。--migrate-local-actions で同じリポジトリのものを $/… 形式に書き換えるか、--ignore-local-actions を明示する。
  • コンテナイメージは固定されない。@sha256: ダイジェストを付ける（Docker イメージを @sha256 ダイジェストで固定する（dockerfile-pin））。
  • 「許可するアクション」の許可リストは、導入後はタグではなく固定したコミット SHA と照合される。actions/checkout@v6 のようなタグ指定の許可エントリーは一致しなくなるため、ワイルドカードかフル SHA に直す。
  • 動く参照（v4、main）を同じ履歴の古いコミットへ戻す lockfile の変更は検知されない。lockfile の差分もレビュー対象にする。
  • GitHub Enterprise Server は拡張の対象外（github.com と *.ghe.com）。

出典

X の元の投稿を開く