GitHub Project を操作する上で利用できる GitHub API と必要なトークン
GitHubには、プロジェクトやタスクの管理ができる project という機能があります。
この project をGitHubのAPIで自動化しようとした際、APIの仕様や必要なトークンの選択に苦労しました。
本記事では project を操作する上で必要となるAPIとトークンについてまとめています。
利用できる GitHub API と必要なトークン（表）
利用できるトークンと GitHub API を簡単に表にまとめたものがこちらです。
| project (v1) | project (v2) | |
|---|---|---|
| GitHub API | v3 (REST API) / v4 (GraphQL) | v4 (GraphQL) |
| GITHUB_TOKEN | o | x |
| GitHub Apps Token | o | △（organizaiton） |
| PAT (classic) | o | o |
project の種類には、旧型の classic project (以降v1) と通常の project (以降v2)があります。
また、project はアクセスレベルの選択ができます。
個人のみの利用な場合は user project、チームや組織で利用する場合は organization projectになります。
project の種類とアクセスレベルによって、APIやトークンが異なるのがややこしいポイントです。
ポイント
project (v2) は GitHub API v4 (GraphQL) からしか操作できない
GitHub API には、バージョンによって v3 （REST API） と v4 （GraphQL） の2つがあります。
これらは互換性があるわけではなく、v4 からしか提供されていないAPIがあります。
今回の project(v2) API は v4 からしか提供されていません。
これらのエンドポイントを使って操作されるのは、projects (classic) のみです。 Projects を管理するには、GraphQL API を使います。
Projects (classic)用 REST API エンドポイント
v4 であれば、project(v1)とproject(v2)の両方ともカバーしているので、そちらを使うのが良さそうです。
GitHub Apps Token で操作できるのは organization project(v2) のみ
アクセスレベルによって、使えるトークンが異なるものややこしいポイントです。
GitHub Apps Token のスコープでは organization project しかアクセスできません。
GITHUB_TOKEN はリポジトリレベルをスコープとしており、projects にはアクセスできません。 projects にアクセスするために、GitHub App (Organization プロジェクトの場合に推奨) または personal access token (ユーザー プロジェクトの場合に推奨) を作成できます。
Actions を使用した Projects の自動化: GitHub Actionsのワークフロー
user project でも利用できたら嬉しいのですが、現在(2024/4)では PAT（もしくは GitHub OAuth App）などの個人の権限を渡すトークンを利用するしかないようです。
github community の disscussions でも言及されていました。
GitHub support confirmed that GitHub Apps cannot access user-level V2 Projects (!!). The only way is to use a PAT or authorize through a GitHub OAuth App.
https://github.com/orgs/community/discussions/46681#discussioncomment-8774842
まとめ
GitHub Project を自動化したいと思い API を触り始めたのですが、トークンの種類ごとのスコープや API のバージョンでできることが異なっていたため、意外と時間がかかりました。
- GitHub API のバージョン (v3/v4) ごとのエンドポイントの仕様を確認する
- トークンの種類とそれぞれのスコープを整理する
この辺りを整理しながらドキュメントを参照することで、必要な情報を素早くキャッチできるのではと思いました。
Discussion