🔑 認証・トークンガイド
Workflow を実行するために必要な PAT（Personal Access Token）の権限設定について説明します。
（ここをクリック）目次
🔐 Q. PAT にはどの権限が必要ですか？
A. Workflow ごとに必要な権限が異なります。アカウントタイプとトークンタイプの組み合わせに応じて、以下の該当パターンを確認してください。
（ここをクリック）個人用アカウント × Fine-grained token
| カテゴリ | 権限 | 必要な Workflow |
|---|---|---|
| Account permissions > Projects | Read and write | ①②⑤ |
| Account permissions > Projects | Read | ⑥ |
| Repository permissions > Administration | Read and write | ③ |
| Repository permissions > Contents | Read and write | release-please |
| Repository permissions > Issues | Read and write | ④ |
| Repository permissions > Issues | Read | ⑤ |
| Repository permissions > Pull requests | Read and write | release-please |
| Repository permissions > Pull requests | Read | ⑤ |
Note: Workflow ③（特殊 Repository 一括作成）では Repository の作成を行うため、 Administration の書き込み権限が必要です。
Note: Workflow ④（Label 一括追加）では Label の作成を行うため、 Issues の書き込み権限が必要です。
Note: Workflow ⑤（Issue/PR 一括紐付け）では対象 Repository の Issue/PR を読み取るため、 Repository の参照権限が追加で必要です。
Note: Workflow ⑥（統合プロジェクト分析）はプロジェクトデータの読み取りのみを行うため、 Projects は Read で十分です。
Note: release-please Workflow では CHANGELOG ・バージョンファイルの更新およびリリース PR の作成・更新を行うため、 Contents（Read and write）と Pull requests（Read and write）が必要です。
（ここをクリック）個人用アカウント × Classic token
| Scope | 必要な Workflow |
|---|---|
project | ①②⑤⑥ |
read:org | ①②⑤⑥ |
repo（または public_repo） | ③, ④, ⑤, release-please（対象 Repository が private の場合は repo） |
Note: Classic token では、個人用アカウント・ Organization を問わずread:orgScope が必要です。 Organization オーナーの場合、read:orgが不足しているとgh projectサブコマンド実行時にunknown owner typeエラーが発生します。
また、個人用アカウントオーナーの場合、gh project field-createが gh CLI v2.88.1 でunknown owner typeエラーを起こす既知のバグがあります（#119、本 Repository では GraphQL API による回避策を適用済み）。
Note: release-please Workflow では GitHub Release の作成やタグの書き込みを行うため、repoScope が必要です。public_repoでは Contents や Pull requests の書き込み権限が含まれないため、 release-please は動作しません。
（ここをクリック）Organization × Fine-grained token
| カテゴリ | 権限 | 必要な Workflow |
|---|---|---|
| Organization permissions > Projects | Read and write | ①②⑤ |
| Organization permissions > Projects | Read | ⑥ |
| Repository permissions > Administration | Read and write | ③ |
| Repository permissions > Contents | Read and write | release-please |
| Repository permissions > Issues | Read and write | ④ |
| Repository permissions > Issues | Read | ⑤ |
| Repository permissions > Pull requests | Read and write | release-please |
| Repository permissions > Pull requests | Read | ⑤ |
Note: Workflow ③（特殊 Repository 一括作成）では Repository の作成を行うため、 Administration の書き込み権限が必要です。
Note: Workflow ④（Label 一括追加）では Label の作成を行うため、 Issues の書き込み権限が必要です。
Note: Workflow ⑤（Issue/PR 一括紐付け）では対象 Repository の Issue/PR を読み取るため、 Repository の参照権限が追加で必要です。
Note: Workflow ⑥（統合プロジェクト分析）はプロジェクトデータの読み取りのみを行うため、 Projects は Read で十分です。
Note: release-please Workflow では CHANGELOG ・バージョンファイルの更新およびリリース PR の作成・更新を行うため、 Contents（Read and write）と Pull requests（Read and write）が必要です。
（ここをクリック）Organization × Classic token
| Scope | 必要な Workflow |
|---|---|
project | ①②⑤⑥ |
read:org | ①②⑤⑥ |
repo（または public_repo） | ③, ④, ⑤, release-please（対象 Repository が private の場合は repo） |
Note: Classic token では、個人用アカウント・ Organization を問わずread:orgScope が必要です。 Organization オーナーの場合、read:orgが不足しているとgh projectサブコマンド実行時にunknown owner typeエラーが発生します。
Note: release-please Workflow では GitHub Release の作成やタグの書き込みを行うため、repoScope が必要です。public_repoでは Contents や Pull requests の書き込み権限が含まれないため、 release-please は動作しません。
🤔 Q. Fine-grained token と Classic token のどちらを使うべきですか？
A. Fine-grained token の使用を推奨します。 理由は以下のとおりです。
- 最小権限の原則: 必要な権限だけを細かく設定できるため、セキュリティリスクを最小限に抑えられる
- Repository 単位のアクセス制御: アクセスできる Repository を明示的に指定できるため、意図しない Repository への操作を防止できる
- GitHub の推奨: GitHub が今後推奨しているトークン形式であり、長期的なサポートが期待できる
参考:
Fine-grained tokenの制約事項については次のセクションを参照してください。
⚠️ Fine-grained token の制約事項
Fine-grained token には以下の制約があります。
- Organization の複数指定不可:
Fine-grained tokenはリソースオーナーとして 1 つの Organization（または個人用アカウント）しか指定できない。複数 Organization の Repository を対象にする場合は、 Organization ごとにPATを作成するかClassic tokenを使用する - 個人用アカウントと Organization の横断不可: 個人用アカウント所有 Repository と Organization 所有 Repository を 1 つの
Fine-grained tokenで横断できない
注意: 上記制約により、 Workflow ⑤ で異なる Organization の Repository を
target_repoに指定する場合は、Classic tokenの使用を推奨します。