📌

GitHub Actions で参照するアクションはコミット SHA で固定するべき

に公開
2026/08/14
1件
# 論外
- uses: foo/action@v1
- uses: foo/action@main

# 危ない
- uses: foo/action@v1.0.0

# まぁ大丈夫
- uses: foo/action@a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0 # v1.0.0

要約

  • アクションを Git タグやブランチで指定しないでください。
  • pinact をインストールしてください。
  • pinact run を実行してください。
$ pinact run

なんで Git タグやブランチ指定ではダメなの?

基本的に Git タグやブランチは書き換え可能だからです。

もしも万が一アクション側のリポジトリが侵害された場合などに、アクションの利用者側は自身の GitHub Actions ワークフロー定義を何も変更していないのに突然 CI が壊れたり、悪意のあるコードが実行されるなどのリスクがあります。

例えば以下のようにアクションを参照している場合、もしも攻撃者によって foo/action リポジトリの v1 タグが書き換えられたときにアクション利用者側の GitHub Actions ワークフロー上で悪意のあるコードが実行されます。

- uses: foo/action@v1 # Git タグで指定

詳しくは以下の記事を読んでください。

https://zenn.dev/shunsuke_suzuki/articles/pinact-pin-github-actions-version

GitHub Actions の action のバージョンの指定には branch や tag を用いる事ができます。
...
しかしこれらの branch や tag の commit hash は immutable ではなく、実行タイミングによって実行される action が変わる可能性があります。そのため、コードを修正していないのに突然 CI が壊れたり悪意のあるコードが実行されてしまうリスクがあります。

pinact - GitHub Actions のバージョンを commit hash で固定

どうしたらいいの?

利用するバージョンのコミット SHA を指定してください。

# こんな感じ
- uses: foo/action@a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0 # v1.0.0

コミット SHA は Git タグやブランチとは違って immutable なので、参照先のアクションの変更による想定外の影響を受けるリスクを軽減することができます。

とはいえ、いちいちアクションのコミット SHA を確認するのは大変なので、前述した Shunsuke Suzuki さんの記事で紹介されている pinact を使いましょう。

https://github.com/suzuki-shunsuke/pinact

Homebrew でのインストール例
$ brew install pinact

pinact run を実行するだけで、Git タグやブランチ指定のアクションをコミット SHA 指定に自動変換してくれます。

$ pinact run
.github/workflows/example.yml
 # ...

 jobs:
   example:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2

       # ...

コミット SHA 指定を強制する

リポジトリ設定でアクションのコミット SHA 指定を強制することもできます。

https://github.blog/changelog/2025-08-15-github-actions-policy-now-supports-blocking-and-sha-pinning-actions/

Enforce SHA Pinning
Require actions to be pinned to a full-length commit SHA

この設定を有効にしておくと、コミット SHA で固定されていないアクションを参照しているワークフローは実行時にエラーになります。

実行ログ
GitHub Actions の実行ログ

Error: The action actions/checkout@v6 is not allowed in <OWNER>/<REPO> because all actions must be pinned to a full-length commit SHA.

https://zenn.dev/shunsuke_suzuki/articles/github-actions-enforce-sha-pinning

お客様の声

「Git タグの書き換えなんて実際に起こるの?」

「確かに理屈として起こりうるのはわかるけど、実際に有名リポジトリの Git タグやブランチが悪意を持って書き換えられることなんてないでしょ?」

たまたまこんな記事を見かけましたので貼っておきますね。

https://www.wiz.io/blog/new-github-action-supply-chain-attack-reviewdog-action-setup
https://semgrep.dev/blog/2025/popular-github-action-tj-actionschanged-files-is-compromised/

「でもメジャーバージョンタグの指定は便利じゃん」

「@v1 みたいに指定しておけば、何もしなくてもマイナー / パッチバージョンのアップデートが勝手に適用されていくから便利じゃん!!」

そういうことでしたら、プロダクトの依存ライブラリ等も全て勝手にアップデートされていった方が絶対に便利なので、たとえば毎日自動で依存ライブラリのバージョンを勝手にアップデートして main ブランチに直接 commit & push する GitHub Actions ワークフローを作ってみるといいかもしれませんね。

えぇ!?!?「それはさすがに危ないからやりたくない」ですって!?!?
「たとえマイナー / パッチバージョンアップデートであっても、破壊的変更や脆弱性の混入などが発生する可能性は決してゼロではない」ですって!?!?!?!?
えぇ〜〜〜〜〜っっっ!?!?!?!?

「アップデートがめんどくさい」

「アクションのバージョンを上げるたびにいちいちコミット SHA を確認するのは大変だしめんどくさいよ!」

どうやら世の中には Dependabot や Renovate などといった便利なツールがあるらしいですよ。これらはいずれもコミット SHA 指定のアクションの自動バージョンアップをサポートしているようです。

もしくは、最新バージョンに上げるだけなら pinact run --update コマンドを使っても大丈夫です。

# 参照しているアクションが最新にアップデートされる
$ pinact run --update

詳細な手順については以下の記事をご参照ください。

https://zenn.dev/kou_pg_0131/articles/gha-update-pinned-actions

「Immutable Releases が有効になってればいいじゃん」

「アクションのリポジトリ側で Immutable Releases が有効になっていれば Git タグの書き換えはできないし安全でしょ?」

https://docs.github.com/en/code-security/concepts/supply-chain-security/immutable-releases

Immutable Releases はデフォルトでは無効になっていますが、あなたが使用するありとあらゆるアクションや、さらにそれらのアクションが内部的に依存しているアクションなども含めた全てのリポジトリで Immutable Releases が有効になっているといいですね。

また、メジャーバージョンのみの Git タグ (v1 など) はマイナー / パッチバージョンアップなどで頻繁に上書き更新するために Release に紐づいていないケースが普通なので、もしもそれらを参照している場合はたとえ Immutable Releases が有効になっていても意味がありませんが、気にしないでください。

「コミット SHA を間違えてしまったとき、見分けがつかない」

「万が一誤って悪意のあるフォークリポジトリのコミット SHA を指定しまう可能性は排除できないし、その時にコミット SHA だと人の目では見分けがつかなくてむしろ危険だよ!」

この機会に是非とも zizmor をお使いになられてください。なりすましコミット SHA を検出するための機能があります。

impostor-commit

Detects commits within a repository action's network that are not present on the repository itself, also known as "impostor" commits.

Audit Rules - zizmor

zizmor の出力例
error[impostor-commit]: commit with no history in referenced repository
  --> ./.github/workflows/foo.yml:19:15
   |
19 |         - uses: actions/checkout@a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0 # v6.0.0
   |           -     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ uses a commit that doesn't belong to the specified org/repo
   |  _________|
   | |
20 | |         with:
21 | |           persist-credentials: false
   | |_____________________________________- this step
   |
   = note: audit confidence → High
   = note: this finding has an auto-fix

「コミット SHA 固定だけで全てのセキュリティリスクを排除できるわけではないよね?」

「例えば参照しているアクションが間接的に他のアクションを Git タグで参照していたり、そもそもアクションの安定バージョンが既に侵害されていたりする場合など、コミット SHA で固定することだけでは排除できないリスクは色々あるよね?」

https://shs.sh

あくまでコミット SHA で固定することは「ワークフロー定義を変更していないのにアクション側の変更によって破壊的な影響を受ける」というリスクを軽減するための対策のひとつにすぎません。
「コミット SHA で固定さえしておけば絶対安全!」というわけでは決してないので、そこは切り分けて考えましょう。

まとめ

細かいし面倒ではありますが、しっかり対応していきましょう。してください。

あわせて読みたい読んでください

https://zenn.dev/kou_pg_0131/articles/gha-script-injection

GitHubで編集を提案

Discussion