gha-sha-reference

syou6162's avatarfrom syou6162

ユーザーがGitHub Actionsのタグ参照をSHA参照に変換するよう要求したときに発動してください。uses:フィールドのタグ参照を自動的にSHA参照（コミットハッシュ + コメント付きバージョン）に変換します。

⭐9stars🔀0forks📁View on GitHub🕐Updated Nov 25, 2025
[CI and CD]

When & Why to Use This Skill

This Claude skill automates the conversion of GitHub Actions tag references to immutable SHA references using the 'pinact' tool. It enhances repository security by ensuring that workflows use specific, verifiable commit hashes instead of mutable version tags, effectively preventing supply chain attacks and ensuring pipeline stability.

Use Cases

  • Security Hardening: Automatically replace version tags (e.g., @v4) with full commit SHAs to follow GitHub's security best practices for third-party actions.
  • Bulk Workflow Migration: Efficiently update all YAML files within the .github/workflows directory to use pinned references in a single operation.
  • Compliance Auditing: Use the built-in diff and check functionality to identify unpinned actions and preview changes before applying them to the codebase.
  • Version Documentation: Maintain readability by automatically appending the original version tag as a comment (e.g., # v4.3.0) next to the SHA hash.
namegha-sha-reference
descriptionユーザーがGitHub Actionsのタグ参照をSHA参照に変換するよう要求したときに発動してください。uses:フィールドのタグ参照を自動的にSHA参照（コミットハッシュ + コメント付きバージョン）に変換します。

GitHub Actions SHA Reference Skill

目的

このスキルはGitHub Actionsワークフローファイル内のuses:フィールドで使用されているタグ参照（例: @v4）を、セキュリティのベストプラクティスに従ってSHA参照（例: @11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2）に自動変換します。

使用タイミング

以下の場合にこのスキルを発動してください：

  • ユーザーが「GitHub ActionsをSHA参照に変換して」と要求したとき
  • ユーザーが「actionsのusesをSHAに書き換えて」と言及したとき

実行手順

1. 変更対象を確認

まず --check --diff オプションで、どのファイルが変更されるかを確認します：

pinact run --check --diff

出力例:

ERROR action isn't pinned
.github/workflows/ci.yaml:10
-       uses: actions/checkout@v4
+       uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
ERROR action isn't pinned
.github/workflows/ci.yaml:11
-     - uses: actions/setup-go@v4
+     - uses: actions/setup-go@4d34df0c2316fe8122ab82dc22947d607c0c91f9 # v4.0.0
ERROR action isn't pinned
.github/workflows/deploy.yaml:15
-       uses: actions/checkout@v4
+       uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0

2. 変換を実行

確認後、pinact run を実行してすべての対象ファイルを一括変換します：

pinact run

pinactは以下を自動的に行います：

  • タグ参照からコミットSHAを取得
  • 最も詳細なバージョンタグ（v4.3.0など）をコメントとして追加
  • .github/workflows/*.{yml,yaml} と action.{yml,yaml} を自動検出して変換

実装例

例1: 基本的な使用方法

ステップ1: 変更対象を確認:

pinact run --check --diff

出力:

ERROR action isn't pinned
.github/workflows/ci.yaml:10
-       uses: actions/checkout@v4
+       uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
ERROR action isn't pinned
.github/workflows/ci.yaml:11
-     - uses: actions/setup-go@v4
+     - uses: actions/setup-go@4d34df0c2316fe8122ab82dc22947d607c0c91f9 # v4.0.0

ステップ2: 変換を実行:

pinact run

変換後のワークフローファイル (.github/workflows/ci.yaml):

name: CI
on: [push]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
      - uses: actions/setup-go@4d34df0c2316fe8122ab82dc22947d607c0c91f9 # v4.0.0

重要な注意事項

すべきこと

  • pinactを使用: GitHub Actions SHA参照変換には専用ツールpinactを使用する
  • まず --check --diff で確認: pinact run --check --diff で変更対象を確認する
  • 一括実行: diffで確認した後、pinact run で全ファイルを一括変換する
  • 変換結果を報告: 何が変換されたかユーザーに伝える

してはいけないこと

  • カスタムスクリプトを作成: pinactという専用ツールがあるので、独自スクリプトは不要
  • いきなり実行: --check --diff で確認せずに pinact run を実行しない
  • エラーを無視: pinactの実行でエラーが出た場合は、そのまま進めずユーザーに報告する

実行前チェックリスト

  • pinactがインストールされている（pinact --versionで確認）
  • pinact run --check --diff で変更対象を確認した
  • diffの出力から変換対象のファイル一覧を把握した

参考リンク