Fork からの PR で GitHub Actions の Secrets が使えない
セキュリティ上、pull_request イベントは fork 側のワークフローに secrets を渡さない仕様。pull_request_target への切り替え、信頼境界を切り分けたジョブ設計、Environments での承認ゲートを組み合わせて安全に解決する。
公開: 更新:
要約
Fork からの PR で secrets が undefined になるのは、意図された仕様である。
悪意ある PR が secret を盗まないように、pull_request イベントでは fork 側ワークフローに secrets を渡さない設計になっている。pull_request_target への切り替え、ジョブ分離、Environment 承認制を組み合わせて安全に対処する。
解決策
1. ジョブを分離する
lint / typecheck など PR 側コードを実行するジョブは pull_request のまま、secrets を使う preview deploy などだけを pull_request_target に切り出す。pull_request_target 側では PR のコードを取り出してもデータとして扱うだけにし、実行しない(npm ci やビルドも実行に当たる)。
on:
pull_request: # PR コードを実行する側(secrets なし)
pull_request_target: # secrets を使う側(PR コードは実行しない)
jobs:
lint:
if: github.event_name == 'pull_request'
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- run: npm ci && npm run lint
preview-deploy:
if: github.event_name == 'pull_request_target'
environment: preview
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4 # base ブランチ(信頼できるスクリプト)
- uses: actions/checkout@v4 # PR 側はデータとしてだけ取り出す
with:
ref: ${{ github.event.pull_request.head.sha }}
path: pr
persist-credentials: false
allow-unsafe-pr-checkout: true # fork の PR の head を取り出すのに必要
- run: ./scripts/deploy-preview.sh pr # base 側のスクリプトで配置し、pr/ の中身は実行しない
env:
PREVIEW_TOKEN: ${{ secrets.PREVIEW_TOKEN }}2026-07-20 以降の actions/checkout@v4(v4.4.0)は、pull_request_target で fork の PR の head を指定すると Refusing to check out fork pull request code で失敗し、allow-unsafe-pr-checkout: true を書いたときだけ取り出す。
取り出したコードを実行しないことが前提のオプションである(Securely using pull_request_target(新しいタブで開く))。
2. PR コードを実行しないジョブ設計にする
Events that trigger workflows(新しいタブで開く) の pull_request_target 節のとおり、pull_request_target は base ブランチの状態で動くことを前提にしている。
PR 側コードを secrets のあるジョブで実行する構成は避ける(取り出すならデータとして扱うだけにする)。
3. Environment で承認ゲート
Settings → Environments で Required reviewers を設定すると、その environment を要求する job は maintainer が手で承認するまで開始されない。
fork PR でも secrets を解決する処理は Environment 越しに通す設計にすれば、人手承認なしには走らない。
4. push トリガーに退避する
on:
push:
branches: [main]リリースやデプロイの本処理は push トリガーに移すと、fork PR から動かす必要が無くなり secrets 問題は根本的に消える。
よくある原因
pull_requestの仕様どおりに動いている。
fork からの PR で動くpull_requestのワークフローには、GITHUB_TOKENを除いて secrets がランナーへ渡されない(Using secrets in GitHub Actions(新しいタブで開く) に明記)。
渡されていないsecrets.FOOを参照する式は空文字になる。GITHUB_TOKENの権限が縮小されている。
同イベントでGITHUB_TOKENも実質 read 相当の権限まで絞られ、コメントや label の付与もできなくなる。- ワークフローが混在している。
secrets を使うデプロイ処理を fork PR と同じワークフローで動かしており、毎回 fork PR で失敗する。 pull_request_targetの checkout の罠にはまっている。pull_request_targetは base ブランチで動くため、actions/checkoutを素で書くと PR 側コードを落とせない。
逆に PR 側コードを安易に落として secrets と組み合わせると重大な脆弱性になる。