マージしたのに本番が変わらない — Vercel の「Git author must have access」を特定して $0 で通す

これは何の指示書か

GitHub と連携した Vercel プロジェクトで、PR をマージしたのに本番サイトが更新されないときの原因特定と回避手順。CI は緑、マージも成功、なのに本番だけ古いまま、という状況を扱う。

よくある誤診は「ビルドキャッシュ」「ブランチ違い」「環境変数」。それらを疑う前に、デプロイが作成すらされず拒否されている可能性を先に潰す。

症状

• PR の Checks に Vercel の項目があり、Git author <ユーザー名> must have access to the project on Vercel to create deployments. と出ている。
• マージ自体は成功し、main には変更が入っている。
• 本番 URL は以前のビルドを返し続ける。
• 特定のメンバーが出した変更のときだけ起きる。別のメンバーのときは出る。

原因

Vercel は、Git 連携で作られるデプロイについて コミットの author が Vercel プロジェクトにアクセス権を持っているかを検査する。権限が無い人が author のコミットは、ビルドされずに Deployment was blocked で終わる。

ここで最も間違えやすい点がひとつある。

author を決めるのはマージ方式ではなく、マージボタンを押した人。

Squash and merge を Create a merge commit に変えても、押したのが権限の無い人なら、できあがるコミットの author はその人になる。方式の選択では直らない。

診断（コマンドだけで確定する。管理画面を開かなくてよい）

GitHub CLI (gh) が使える前提。<OWNER>/<REPO> は自分のものに置き換える。

1. 本番デプロイの結果を見る

gh api "repos/<OWNER>/<REPO>/deployments?environment=Production&per_page=5" --jq '.[].id'

出た ID それぞれについて state を見る。

gh api "repos/<OWNER>/<REPO>/deployments/<ID>/statuses" --jq '.[0] | {state, description}'

{"state":"failure","description":"Deployment was blocked"} なら、この問題。

2. 作者と結果を突き合わせる

for id in $(gh api "repos/<OWNER>/<REPO>/deployments?environment=Production&per_page=10" --jq '.[].id'); do
  sha=$(gh api "repos/<OWNER>/<REPO>/deployments/$id" --jq '.sha[0:7]')
  who=$(gh api "repos/<OWNER>/<REPO>/commits/$sha" --jq '.commit.author.email')
  st=$(gh api "repos/<OWNER>/<REPO>/deployments/$id/statuses" --jq '.[0].state')
  echo "$sha $who $st"
done

作者ごとに success と failure がきれいに分かれていれば確定。分かれていなければ別の原因なので、この指示書は当たらない。

3. 自分がそのプロジェクトに届くか、Vercel 側に直接聞く

GitHub の情報だけで「権限が無い」と断定しない。Vercel に聞く。

npx vercel whoami
npx vercel teams ls
npx vercel project ls --scope <TEAM_ID>

<TEAM_ID> は PR の Vercel チェックのリンクに teamId= として入っている。The specified scope does not exist が返れば、そのアカウントからはプロジェクトに到達できない。

直し方

A. いますぐ本番を更新する（$0・権限のある人の操作2クリック）

プロジェクトに権限のある人が、PR をどれか1本マージする。 そのマージコミットの author がその人になるので、デプロイが通り、main の現在の内容がまとめて本番に出る。ブロックされた変更もそこに含まれるため、作り直しは不要。

待機中の PR が無ければ、権限のある人が空コミットを push しても同じ効果になる。

git commit --allow-empty -m "chore: trigger production deploy"
git push origin main

B. 再発させない（$0・初回だけ1操作）

Deploy Hook を使い、author 検査を通らない経路でデプロイを起こす。

1. 権限のある人が Vercel のプロジェクト設定で Deploy Hook を作り、URL を GitHub リポジトリの Secrets に VERCEL_DEPLOY_HOOK として登録する。
2. 下のワークフローを置く。

name: Trigger Vercel deploy
on:
  push:
    branches: [main]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Call deploy hook
        run: curl -fsS -X POST "${{ secrets.VERCEL_DEPLOY_HOOK }}"

Deploy Hook は誰が push したかを見ないので、以後は author に関係なく本番が更新される。

C. 根本解決（有料になる場合がある）

ブロックされているメンバーを Vercel プロジェクトに追加する。個人スコープなら無料だが、チームスコープではプランによって課金対象になることがある。A と B で足りるなら、先にそちらを使う。

落とし穴

• CLI の成功を信じない。 vercel deploy --prod は作成に失敗しても exit 0 で終わることがある。必ず上の deployments/<id>/statuses で state を確認する。
• マージ方式を変えて様子を見ない。 原因が author である以上、方式を変えても結果は変わらない。押す人を変える。
• 「権限が無いはず」で止めない。 Vercel の CLI か API を直接叩いて確認する。GitHub 側の情報は根拠にならない。
• 依頼するときは「人」を書く。 「merge commit を選んでください」ではなく「あなたがマージボタンを押してください」と書く。方式の話にすると相手は方式だけ変えて同じ結果になる。

完了の判定

A または B を実施したあと、もう一度これを実行する。

gh api "repos/<OWNER>/<REPO>/deployments?environment=Production&per_page=1" --jq '.[0].id'
gh api "repos/<OWNER>/<REPO>/deployments/<上の ID>/statuses" --jq '.[0].state'

success が返れば本番に出ている。ここまで確認してから完了と呼ぶ。