AIが書いたGitHub Actions、マージ前に確認する3点：権限・SHA固定・pull_request_target

AIが書いたGitHub Actions、マージ前に確認する3点：権限・SHA固定・pull_request_target

【中級者向け】YAMLの基本的な書き方とGitHubのPull Request操作が分かる人向け。GitHub Actionsの権限モデルを詳しく知らなくても、本文中で必要な用語をその都度説明する。

Claude CodeやCodexのようなAIエージェントに「テストを自動実行するworkflowを作って」と頼むと、数十秒で動くYAMLが出てくる。実際にpushしてグリーンチェックが付けば、そのままマージしてしまいがちだ。だが、そのYAMLに`permissions`の指定がなかったり、外部の`uses:`アクションがタグ名のまま貼り付けられていたり、`pull_request_target`をよく分からないまま使っていたりすると、「動く」ことと「安全である」ことは別問題になる。

この記事では、GitHub公式ドキュメントの一次情報にもとづいて、AIが生成したworkflowファイルをマージする前に確認すべき3つのポイント（トークン権限・アクションの固定方法・危険なトリガーの扱い）を、そのまま使えるYAML例とコマンドつきで整理する。

**TL;DR** - `permissions:`を書かないと、GITHUB_TOKENに想定より広い権限が渡ることがある。ジョブ単位で最小権限を明示する。 - 外部アクションは`@v4`のようなタグではなく、コミットSHAで固定すると改ざんに強くなる。GitHub API(`api.github.com`)を叩けば、読者自身の手で最新のSHAを確認できる。 - `pull_request_target`と`workflow_run`は、フォークのコードを誤ってチェックアウト・実行すると、リポジトリの書き込み権限とシークレットごと乗っ取られる「pwn request」という攻撃パターンにつながる。

Claude Codeに「テスト用のGitHub Actionsを作って」と頼んだら一発で動くYAMLが出てきたので、そのままマージしちゃいました…まずかったですか？

動くこと自体は問題ありません。ただ、権限が広すぎたり、外部アクションがタグ指定のままだったり、pull_request_targetの扱いが甘かったりすると、動くのに安全ではない状態になっていることがあります。この記事で3つのチェックポイントを順番に見ていきましょう。

この記事でできること

対象読者

確認環境・確認日

背景：なぜ「動く」workflowがそのまま危ないのか

GitHub Actionsのjobは、既定で`GITHUB_TOKEN`という一時的な認証トークンを受け取る。このトークンは`github.token`コンテキスト経由でどのstepからもアクセスでき、`permissions`キーで制限しない限り、リポジトリに対して比較的広い操作ができてしまう。公式ドキュメントは「GITHUB_TOKENには必要最小限の権限だけを与えるべきで、既定の権限をリポジトリ内容の読み取りのみに設定するのがよい実践だ」と明記している。

AIエージェントに「テストを実行するworkflowを作って」とだけ頼むと、動作すること自体を優先した最小構成のYAMLが返ってくることが多く、`permissions`の指定が省略されがちだ。省略されていても多くの場合は動いてしまうため、レビューで気づかない限り、そのまま本番のリポジトリに残り続ける。

さらに、workflowの中で使う外部アクション（`uses: owner/action@タグ`のような行）は、そのアクションのリポジトリが乗っ取られたり、悪意あるコードを混入されたりすると、workflowを実行するたびに攻撃者のコードがGITHUB_TOKENと同じ権限で動く。公式ドキュメントは「単一のアクションが侵害されただけで、リポジトリの全シークレットへのアクセスと書き込み権限を攻撃者に渡しかねない」と説明しており、サードパーティアクションを使うこと自体に一定のリスクがあることを前提にしている。

権限を絞らなくても普通に動いているので、今のままで十分な気がしてしまいます…

動いているのは、今のリポジトリ設定がたまたま守ってくれているだけかもしれません。GITHUB_TOKENの既定の権限は環境によって変わるので、workflow側で明示しておかないと、設定を変えた瞬間に想定より広い権限が渡ることがあります。

AIが書いたYAMLをレビューする/しないで何が変わるか

必要なもの

全体像：3つのチェックポイント

AIが生成したworkflowをレビューする流れは、次の3つのチェックを順に当てるだけでよい。

この3つは独立しているので、既存のworkflowに後から追加する形でも、AIに直させる形でも適用できる。以降、それぞれのチェックを具体的なYAML例で見ていく。

チェック1: GITHUB_TOKENの権限を最小化する

まず、workflow全体またはジョブ単位で`permissions`キーを明示する。公式チュートリアルに掲載されている例をそのまま使うと、次のようになる。

name: Open new issue
on: workflow_dispatch
jobs:
  open-issue:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      issues: write
    steps:
      - run: |
          gh issue --repo ${{ github.repository }} \
            create --title "Issue title" --body "Issue body"
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

ポイントは、`gh` CLIやREST APIを呼ぶだけのジョブに対して、必要な権限（この例では`contents: read`と`issues: write`）だけを列挙している点だ。AIが生成したworkflowに`permissions`が無ければ、まずそのジョブが実際に何をしているか（コードを読むだけか、Issueを作るのか、PRにコメントするのか）を洗い出し、対応する権限だけを足す。

REST APIを直接叩く場合も考え方は同じで、公式チュートリアルには次の例が載っている。

name: Create issue on commit
on: [push]
jobs:
  create_issue:
    runs-on: ubuntu-latest
    permissions:
      issues: write
    steps:
      - name: Create issue using REST API
        run: |
          curl --request POST \
            --url https://api.github.com/repos/${{ github.repository }}/issues \
            --header 'authorization: Bearer ${{ secrets.GITHUB_TOKEN }}' \
            --header 'content-type: application/json' \
            --data '{
              "title": "Automated issue for commit: ${{ github.sha }}",
              "body": "This issue was automatically created by the GitHub Action workflow **${{ github.workflow }}**."
            }' \
            --fail

`permissions`を明示せずにこのworkflowを動かすと、既定の権限設定（リポジトリまたは組織の設定次第で「読み取りのみ」か「読み書き」）に依存してしまう。AIが出したYAMLに`permissions`が無い場合は「動いたから問題ない」ではなく、「今のリポジトリ設定にたまたま守られている」だけの可能性を疑うべきだ。

チェック2: 外部アクションをコミットSHAで固定する

次に、workflowの中で`uses:`に外部アクションを指定している行を確認する。`actions/checkout@v4`のようにタグ名で指定している場合、そのタグが指す中身は将来変わりうる。公式ドキュメントは「タグはリポジトリへのアクセス権を持つ攻撃者によって移動・削除されることがあり、作者を信頼していてもこのリスクは残る」と説明している。

より安全なのは、コミットSHA（40文字の完全なハッシュ値）で固定する方法だ。公式ドキュメントいわく、「コミットSHAでの固定は、現時点でアクションをイミュータブル（不変）なリリースとして扱う唯一の方法」であり、攻撃者がバックドアを仕込むにはSHA-1の衝突を作る必要があるため難易度が上がる。

固定に使うSHAは、想像やAIの回答をそのまま信じるのではなく、自分の手でGitHub APIから取得できる。次のコマンドで、任意のアクションの最新リリースとそのコミットSHAが分かる。

# 最新リリースのタグ名を調べる(例: actions/checkout)
curl -s "https://api.github.com/repos/actions/checkout/releases/latest" \
  | grep -E '"tag_name"|"published_at"'

# そのタグが指すコミットSHAを調べる(<タグ名>を上の結果に置き換える)
curl -s "https://api.github.com/repos/actions/checkout/git/ref/tags/<タグ名>" \
  | grep '"sha"'

このコマンドを2026-09-27に実際に実行したところ、`actions/checkout`の最新タグは`v7.0.1`（公開日2026-07-20）で、対応するコミットSHAは`3d3c42e5aac5ba805825da76410c181273ba90b1`だった。これを使うと、workflow内の指定は次のようになる。

steps:
  - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1

行末のコメントにタグ名を残しておくと、後から見返したときにどのバージョン相当かが分かりやすい。**ここで示したSHAは2026-09-27時点の値であり、読者が実行する時点の最新版とは異なる。** 必ず自分でコマンドを実行し、その時点の値を使うこと。

SHAで固定する前に、「そのコミットが本当にアクション本体のリポジトリのものか、フォークのものではないか」を確認するのも公式の推奨事項だ。`git/ref/tags/`のAPIレスポンスに含まれるコミットURL（`object.url`）が、目的のリポジトリ（例では`actions/checkout`）を指しているかを見ればよい。

外部アクションをSHAで固定しました。これでもう安心ですよね？

権限とSHA固定は、それぞれ別のリスクに効く対策です。もう一つ、pull_request_targetというトリガーの使い方を誤ると、フォークから送られたPull Requestだけで書き込み権限とシークレットを奪われる経路が残っています。次はそこを見ていきましょう。

チェック3: pull_request_target / workflow_run の危険な組み合わせを避ける

3つ目は、AIが提案しがちな便利なトリガーの見落としだ。`pull_request`イベントは、フォークから送られたPull Requestであってもマージコミットからworkflowファイル自体を実行するため、GitHubは既定でこのイベントに読み取り専用のGITHUB_TOKENしか渡さず、他のシークレットへのアクセスも制限している。

一方`pull_request_target`は、workflowファイル自体をベースリポジトリのデフォルトブランチから実行する。そのため「信頼されたコードしか動かない」という前提のもとで、書き込み可能なGITHUB_TOKENとシークレットへのアクセスが渡される。ここで問題になるのは、`actions/checkout`にPull Requestのhead（フォーク側の変更内容）を指定して、そのコードをテストやビルドで実行してしまうケースだ。公式ドキュメントはこれを「pwn request」と呼び、次のような形を危険なパターンとして挙げている。

# 危険な例：pull_request_targetでフォークのコードをチェックアウトし、
# 直後のステップでそのコードを実行してしまう
on: pull_request_target
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
        with:
          ref: ${{ github.event.pull_request.head.sha }}
      - run: make test   # フォークのMakefileが攻撃者の権限昇格に使われうる

`actions/checkout`のstep自体は無害だが、直後に`make test`のようなコマンドでフォーク由来のファイル（Makefile、package.json、設定ファイルなど）を実行すると、攻撃者はPull Requestを送るだけで、ベースリポジトリのシークレットとGITHUB_TOKENを使ったコマンド実行を狙えてしまう。

対策として公式が挙げているのは次の3点だ。

直したつもりですが、ちゃんと効いているか自分で確認する方法はありますか？

はい、新しいツールを入れなくても、YAMLとGitHub APIの出力を突き合わせるだけで確認できます。3つのチェック項目に沿って見ていきましょう。

動作確認：設定が効いているか確かめる方法

設定を直したら、次の3つを確認する。

いずれも新しくツールを導入する必要はなく、YAMLとGitHub APIの出力を読み合わせるだけで確認できる。

応用・実践パターン

パターン1: 複数の外部アクションを一括で洗い出すスクリプト

workflowファイルの中でタグ指定のままになっているアクションを機械的に洗い出す、簡単なシェルスクリプトの例。`.github/workflows/`以下の全YAMLから`uses:`行を抜き出し、SHA固定済みかどうかを判定する。

#!/usr/bin/env bash
set -euo pipefail

# .github/workflows以下のuses:行から owner/repo@ref を抽出し、
# refが40桁の16進数(=コミットSHA)かどうかを表示する
grep -rhoE 'uses:\s*[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+@[A-Za-z0-9._-]+' .github/workflows \
  | sed -E 's/uses:\s*//' \
  | while IFS='@' read -r action ref; do
      if [[ "$ref" =~ ^[0-9a-f]{40}$ ]]; then
        echo "OK(SHA固定済み): $action@$ref"
      else
        echo "要確認(タグ指定): $action@$ref"
      fi
    done

「要確認」と出たアクションだけ、前述のcurlコマンドで最新のコミットSHAを調べて置き換えれば、workflow全体を一つずつ手で見比べる必要がなくなる。

パターン2: リポジトリの性質に応じた使い分け

パターン3: 固定方法どうしの比較

SHA固定してしまえば、あとは放置していても大丈夫ですか？

そこは一つ注意が必要です。SHA固定にはDependabotのセキュリティアラートが働きにくくなるというトレードオフがあります。更新確認の仕組みは別に用意しておきましょう。

運用時の注意点

SHA固定には一つ知っておくべきトレードオフがある。公式ドキュメントによれば、Dependabotは「セマンティックバージョニング(タグ)を使っているアクションに対してのみ脆弱性アラートを作成し、SHAで固定されたアクションに対してはアラートを作成しない」。つまり、SHA固定だけを行って放置すると、そのアクションに新しい脆弱性が見つかっても気づく手段が減ってしまう。SHA固定を導入するときは、更新のタイミングを別途決めておく(定期的に前述のcurlコマンドで最新版を確認する、リリースノートを確認するなど)ことが必要になる。

AIが生成したworkflowにありがちな3つの落とし穴

注意点・制限事項

早見表

権限・SHA固定・pull_request_targetの3点、どれも既存のworkflowに後から足せそうですね。

その通りです。AIが生成したYAMLを丸ごと書き直す必要はなく、レビューの観点として3つ覚えておくだけで、既存のworkflowにも新しく作るworkflowにも使えます。

まとめ

参考にした公式情報