できない.dev

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 問題は根本的に消える。

よくある原因

  1. pull_request の仕様どおりに動いている。
    fork からの PR で動く pull_request のワークフローには、GITHUB_TOKEN を除いて secrets がランナーへ渡されない(Using secrets in GitHub Actions(新しいタブで開く) に明記)。
    渡されていない secrets.FOO を参照する式は空文字になる。
  2. GITHUB_TOKEN の権限が縮小されている。
    同イベントで GITHUB_TOKEN も実質 read 相当の権限まで絞られ、コメントや label の付与もできなくなる。
  3. ワークフローが混在している。
    secrets を使うデプロイ処理を fork PR と同じワークフローで動かしており、毎回 fork PR で失敗する。
  4. pull_request_target の checkout の罠にはまっている。
    pull_request_target は base ブランチで動くため、actions/checkout を素で書くと PR 側コードを落とせない。
    逆に PR 側コードを安易に落として secrets と組み合わせると重大な脆弱性になる。