actions-pinning

actions-pinning

GitHub Actions ワークフロー、複合アクション、再利用可能なワークフロー内のすべての uses: 参照をコミット SHA に固定し、各 SHA が指定されたアクションリポジトリに属していることを検証し、Dependabot で固定を最新の状態に保ちます。

このスキルの対象は、サプライチェーンの固定のみです。同じワークフローファイルに対する Token-Permissions と Dangerous-Workflow の強化は /oss-hygiene、実行時間の短縮は /ci-optimize が担当します。これらは個別に実行してください。

プロトコル

1. 一覧化

同梱のスキャナーを実行し、すべてのワークフローおよび複合アクション／再利用可能なワークフローファイルを調べます。

python3 scripts/pin_check.py .

スキャナーは .github/workflows/**、.github/actions/**、ツリー内のすべての action.yml または action.yaml マニフェストを走査します。VCS および依存関係のディレクトリ（.git、.hg、.svn、node_modules、.venv、venv、__pycache__、dist、build、.tox、target）はスキップします。./vendor/... 参照によってベンダー化されたアクションが実行される可能性があるため、vendor/ はスキャンします。すべての uses: 行について (file, line, action, ref, status) の表を出力し、固定されていない参照がある場合は終了コード 1 で終了します。以降の手順をスクリプトで実行する場合は、--json を使用して機械可読な出力を取得します。

スキャナーは YAML パーサーではなく、正規表現を使用します。各 uses: 値を囲む、一致した引用符のペアを 1 組削除します。既知の制限が 2 つあります。いずれかに該当する場合は、ワークフローを手動で確認してください。

• run: | ブロックスカラー内の uses: 行は、誤った行として検出されます。
• - {uses: owner/repo@v1} のようなフロースタイルのマッピングは、検出されません。

2. 分類

スキャナーは各参照に 1 つのステータスを割り当てます。

ステータス	意味	必要な対応
pinned-sha	すでに 40 文字の完全なコミット SHA で固定されています	なし
unpinned-tag	v4 や v4.1.0 のようなタグ形式の参照です	SHA に解決します
unpinned-branch	main のような一般的なブランチ名です	SHA に解決します
unpinned-ref	release/v1 のようなその他の参照です。種類は不明です	SHA に解決します
unpinned-commit	短い SHA de0fac2 や大文字の 40 文字 SHA など、コミット形式の 16 進数参照です	完全な小文字の SHA に解決します
missing-ref	@ref がありません	SHA に解決します
invalid-self-ref	@ref のサフィックスが付いた $/path 形式の自己リポジトリ参照です	@ref のサフィックスを削除します
local	ローカルの ./path アクション、または $/path 形式の自己リポジトリ参照です	スキップします — サプライチェーンのリスクではありません
docker	docker://image 参照です	個別にフラグを立てます — SHA 固定はこのスキャナーではなく、イメージダイジェストに適用されます

3. 各参照をコミット SHA に解決

次の検出結果ごとに実行します：unpinned-tag、unpinned-branch、unpinned-ref、unpinned-commit、missing-ref。

# Tag: the ref object is the commit (lightweight) or a tag object (annotated).
gh api repos/{owner}/{repo}/git/ref/tags/{tag} --jq '.object'

# Branch: the ref object is the commit directly.
gh api repos/{owner}/{repo}/git/ref/heads/{branch} --jq '.object.sha'

# Annotated tag: dereference the tag object to get the commit SHA.
gh api repos/{owner}/{repo}/git/tags/{tag_sha} --jq '.object.sha'

unpinned-ref の場合は、まず tags/ パスを試し、次に heads/ パスを試してください。

unpinned-commit の場合、タグパスとブランチパスでは参照を解決できません。コミットエンドポイントを使って解決すると、完全な小文字の SHA が返されます。

gh api repos/{owner}/{repo}/commits/{ref} --jq '.sha'

なりすましコミットの確認 — 固定を書き換える前に必ず実行してください。 解決された SHA が、フォーク、書き換えられた参照、または偽装された値ではなく、実際にそのアクション自身のリポジトリに属していることを確認します。

gh api repos/{owner}/{repo}/commits/{sha}

ここで 404 が返された場合、その SHA はそのリポジトリに属していません。処理を中断して再度解決してください。未検証の SHA を書き込まないでください。

検証が完了したら、行を書き換えます。

uses: owner/repo@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2

元のタグは末尾のコメントとして残してください。タグは人が読めるバージョンマーカーであり、SHA は強制される固定値です。

4. Dependabot でピンを最新に保つ

assets/dependabot-actions-snippet.yml にある github-actions エコシステムのエントリを追加するか、既存の dependabot.yml に マージします。Dependabot はタグの更新を新しいコミット SHA に自動的に 解決し、バージョンコメントを更新した PR を作成します。後から手動で ピンを編集するのではなく、これらの PR を確認してマージしてください。

2026-07-14 時点では、セキュリティ更新以外のバージョン更新には、 デフォルトで 3 日間のレジストリ利用可能性クールダウンが適用されます。 新しく公開されたタグは、この期間を過ぎるまで Dependabot の PR に 表示されません。出典については references/policy.md を参照してください。

リポジトリ内のすべてのエコシステムを対象にした dependabot.yml 全体のひな形には、/oss-hygiene を使用してください。このスキルが 管理するのは github-actions エントリのみです。

5. リポジトリと組織のピン留めポリシー

GitHub では、許可されたアクションのポリシーレベル（リポジトリ、組織、 またはエンタープライズ）で SHA ピン留めを強制できます。また、特定の アクションを完全にブロックすることもできます。変更を提案する前に、 依頼の対象範囲における現在のポリシーを確認してください。

# Repository scope.
gh api repos/{owner}/{repo}/actions/permissions

# Organization scope. Use this for an organization-wide request.
gh api orgs/{org}/actions/permissions

これらは読み取り操作です。ユーザーからその変更に対する明示的な許可を 得ていない限り、対応する書き込みエンドポイント （PUT repos/{owner}/{repo}/actions/permissions、 PUT orgs/{org}/actions/permissions、および selected-actions／ allowed_actions の各バリエーション）は決して呼び出さないでください。 ポリシーの変更によって、ほかのワークフローが実行できなくなる場合が あります。

SHA ピン留めポリシーが適用されるのはアクションのみです。このポリシー の下でも再利用可能なワークフローではタグを使用できます。そのため、この スキルでは再利用可能なワークフローの参照も独自にピン留めします。

6. ワークフロースクリプト内の可変ダウンロードを検出する

正規表現によるピン留めの対象は uses: のみです。各ワークフローを 確認する際は、ピン留めされたアクションの仕組みを介さずにコードを取得 する run: ステップも報告してください（検出結果のみ。書き換えは しません）。

• リモートスクリプトをシェルに直接渡す curl ... | sh または curl ... | bash。
• バージョンまたはチェックサムが指定されていない URL からの wget。
• バージョンがピン留めされていない pip install package （または npm install、gem install など）。

これらは、アクションがピン留めされていない場合と同様のサプライチェーン リスクですが、修正方法はエコシステムごとに異なり、ビルドの動作を変更 することもよくあります。報告はしますが、書き換えはしないでください。

7. オプション：zizmor

zizmor がインストールされている場合は、別の見解を得るために実行します （このスキャナーが確認しない bot-conditions や複合アクションの内部も チェックします）。

zizmor .github/workflows/

インストールされていない場合は、何も報告せずにスキップしてください。 これはオプションのツールであり、必須のゲートではありません。

8. 検証

書き換えのバッチごとに、スキャナーを再実行してください。

python3 scripts/pin_check.py . && echo "all uses: references pinned"

終了コードが 0 で、unpinned-tag、unpinned-branch、unpinned-ref、 unpinned-commit、missing-ref、invalid-self-ref の行がなければ、 すべての対応可能な参照がピン留めされています。local と docker の 行は個別に報告してください。これらは情報提供のみを目的としており、 失敗ではありません。

このスキルの対象外

• Token-Permissions と Dangerous-Workflow の強化（最小権限の permissions: ブロック、pull_request_target のリスク、 ${{ github.event.* }} のシェルへの埋め込み）には、/oss-hygiene を使用してください。
• CI の実行時間の短縮には、/ci-optimize を使用してください。
• Actions 以外のエコシステムを対象にした dependabot.yml 全体の選定や 作成には、/oss-hygiene を使用してください。
• リポジトリの所有者からその書き込みに対する明示的な許可を得ずに、 組織全体に適用される許可されたアクションのポリシーを適用すること。

参考資料

• references/policy.md — uses: の構文、SHA ピン留め、許可された アクションのポリシー、SHA 解決エンドポイント、Dependabot の クールダウン、zizmor に関する引用元の一次資料。
• scripts/pin_check.py — 手順 1、2、8 で使用する一覧化・分類スキャナー （--self-test は埋め込みのフィクスチャを実行します。 --json は機械可読形式の出力を行います）。
• assets/dependabot-actions-snippet.yml — dependabot.yml 用の github-actions エコシステムのエントリ。