GitHub Actions ワークフロー用ロックファイルの導入と運用ガイド

セクション：背景と重要性

• セキュリティ向上: Git からワークフローを取得するため、以前は完全なコミット SHA をピン留め（固定）することが推奨されていました。
• タグのリスク: タグは変更可能であり、攻撃者が安全だったタグを悪意あるコードへ差し替えるようなサプライチェーン攻撃の対象となり得ます。
• 新しい対応策: GitHub Actions には現在、ワークフロー用のロックファイルがサポートされています。

セクション：インストールとロック処理

インストール

gh CLI

gh-actions-lock

$ gh extension install github/gh-actions-lock
✓ Installed extension github/gh-actions-lock

ロック処理（Lock 'em）

リポジトリ内で以下のコマンドを実行します。

$ gh actions-lock
✓ All 1 workflows valid

これにより、ワークフロー内のアクションの指定が

vX.Y.Z

変更例（Diff）

コミット SHA がタグに置換される様子です。

--git a/.github/workflows/lint.yml b/.github/workflows/lint.yml
 index 946971c..3503e07 100644
--- a/.github/workflows/lint.yml
+++ b/.github/workflows/lint.yml
@@ -13,7 +13,7 @@ jobs:
     runs-on: ubuntu-latest

     steps:
-      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: actions/checkout@v7.0.1
         with:
           persist-credentials: false
-      - uses: j178/prek-action@44924fe9ef4a6f88253c4b6b1bf11c689d3ce53d # v3.1.0
+      - uses: j178/prek-action@v3.1.0

また、

.github/workflows/actions.lock

gh actions-lock

生成されるロックファイル例

# このファイルは `gh actions-lock` により機械的に生成されています。
# 手動での編集はおやめください。更新には `gh actions-lock` を実行してください。
# ドキュメント: https://gh.io/actions-lockfile
version: 'v0.0.3'
workflows:
    '.github/workflows/lint.yml':
        - 'actions/checkout@v7.0.1'
        - 'j178/prek-action@v3.1.0'
dependencies:
    'actions/checkout@v7.0.1':
        ref: 'v7.0.1'
        commit: 'sha1-3d3c42e5aac5ba805825da76410c181273ba90b1'
        owner_id: 44036562
        repo_id: 197814629
    'j178/prek-action@v3.1.0':
        ref: 'v3.1.0'
        commit: 'sha1-44924fe9ef4a6f88253c4b6b1bf11c689d3ce53d'
        owner_id: 10510431
        repo_id: 1052387486

手順: 変更されたワークフローおよび新しいロックファイルをコミットしてください。

セクション：既存ツールとの互換性（Renovate と Dependabot）

• 対応状況: Renovate と Dependabot の両ツールがすでにロックファイルに対応しています。
• 自動更新: 定期的な更新操作により、ロックファイルも自動的に更新されます。
• 注意点: クールダウン期間の設定を忘れないでください。

セクション：検証（Validate）

GitHub は、ロックファイルが最新かつ破損していないことを CI で確認することを推奨しています。独立したジョブとして検証を行うワークフロー例を示します。

name: Lint
on: [push, pull_request, workflow_dispatch]
permissions: {}
env:
  FORCE_COLOR: 1
  RUFF_OUTPUT_FORMAT: github

jobs:
  lint:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v7.0.1
        with:
          persist-credentials: false
      - uses: j178/prek-action@v3.1.0

  # .github/workflows/actions.lock がワークフローと同期外にある場合、
  # またはロックされたピンが上流で検証に失敗した場合に失敗します。
  lockfile:
    runs-on: ubuntu-slim
    env:
      GH_TOKEN: ${{ github.token }}

    steps:
      - uses: actions/checkout@v7.0.1
        with:
          persist-credentials: false
      - run: gh extension install github/gh-actions-lock --pin v0.4.1
      - run: gh actions-lock --verify

重要な注意点

• 軽量ランナー: ここでは検証用に軽量な

  ubuntu-slim

  ランナーを使用しています。
• バージョン管理:

  v0.4.1

  にピン留めしていますが、将来的には更新するか自動化方法を検討する必要があります。
• 再実行の必要性:
  • ワークフロー内のアクションを最近変更した場合、

    gh actions-lock

    を再実行してロックを更新する必要があります。

  • lint.yml

    内に検証ステップを追加しても、すでに

    actions/checkout

    がロックされているため実質的な変更はありません（ただし CI はその状況を認識します）。
  • 新しいファイル（例：

    verify-lockfile.yml

    ）を作成した場合は、それに対して再度ロック処理を行う必要があります。

セクション：セキュリティリンター「zizmor」の導入

zizmor は GitHub Actions 用のセキュリティリンターであり、強く推奨されます。利用していない場合はぜひ導入してください。

• SHA ピン留め: v1.32.0 以前のパッケージは SHA ピン留めを促しますが、v1.32.0 が初めてロックファイルに対応したバージョンです。
• 設定方法:

  prek

  で利用している場合は、

  .pre-commit-config.yaml

  に

  zizmor

  の設定を追加または更新してください。

- repo: https://github.com/zizmorcore/zizmor-pre-commit
  rev: v1.32.0
  hooks:
    - id: zizmor

セクション：完了と参照事例

ロック処理が完了しました！コミットしてプッシュしましょう。

参考事例

• python-pillow/Pillow#10428
• python/release-tools#477
• python/miss-islington#758
• python/cpython#16181