GitHub の Fine-grained PAT で権限不足になり push / API 呼び出しができない
Fine-grained Personal Access Token は対象リポジトリと細粒度の permissions を都度許可する仕組み。
Contents や Pull requests に Read and write が無いと push や PR 操作が 403 になる。
PAT を編集して必要な権限を付与する。
公開:
要約
Fine-grained PAT は Classic PAT と違い、リポジトリ単位かつ細粒度な権限を都度付与する仕組み。Repository access にリポジトリが入っていなかったり、Contents / Pull requests の権限が不足していると 403 Permission denied や Resource not accessible by personal access token で失敗する。
GitHub 設定画面で PAT を編集し、必要な permissions を付与し直す。
よくある原因
- PAT 発行時に
Repository accessをPublic Repositories (read-only)のまま作成しており、対象のプライベートリポジトリが含まれていない Repository permissionsのContentsがReadのままでgit pushが拒否される- PR 作成 API を呼ぶのに
Pull requests: Read and writeを付け忘れている - 組織リポジトリで PAT が組織の承認待ちのままになっている
- Classic PAT の
reposcope の感覚で扱い、Fine-grained PAT には scope ではなく permissions があることを認識していない
解決策
1. 必要な permissions を付与する
Settings > Developer settings > Personal access tokens > Fine-grained tokens で対象 PAT を開いて編集する。
| やりたいこと | 必要な Repository permission |
|---|---|
| git push | Contents: Read and write |
| PR の作成・コメント | Pull requests: Read and write |
| Actions の workflow を起動 | Actions: Read and write |
| Issue 操作 | Issues: Read and write |
| Secret の参照 | Secrets: Read |
API ごとの必要権限の対応表は Permissions required for fine-grained personal access tokens に網羅されている。
最小権限の原則で必要分だけ付与する。
2. リポジトリ選択を確認
Repository access を Only select repositories にして対象リポジトリを明示的に追加する。All repositories は将来追加分も含まれるので、限定したい場合は前者にする。
3. 組織側の承認
組織のリポジトリで使う場合、組織の管理者が PAT を承認する必要があるケースがある。Organization settings > Personal access tokens > Pending requests で承認待ちを確認する。
組織ポリシーで Fine-grained PAT 自体がブロックされている場合は、GitHub App の installation token に切り替える。
4. 権限変更後は再認証
トークン文字列を再生成 → 環境変数（GITHUB_TOKEN / GH_TOKEN）や git credential に書き直す。
Git Credential Manager を使っている場合は古い資格情報を消す。
git credential-manager erase
# or
gh auth refresh -s repo,workflow権限変更だけしてトークン文字列を再生成していないと、古いキャッシュが残って 403 が継続することがある。