GitHub API は、GitHub のほぼすべての機能をプログラムから操作するための API だ。リポジトリ、Issue、Pull Request、Actions、Releases を REST と GraphQL の二系統で扱える。

REST と GraphQL の使い分け

GitHub は REST API と GraphQL API の両方を提供しており、ここを理解すると効率が変わる。単純な単発操作（Issue を 1 件作る、ファイルを 1 つ読む）は REST が素直だ。一方、「リポジトリ一覧と、それぞれの直近の Issue とラベルをまとめて取りたい」といった入れ子のデータを一度に取る場合は GraphQL が圧倒的に少ないリクエスト数で済む。REST で同じことをやると何往復もして、レート制限を早く食い潰す。

典型的な使いどころ

CI/CD パイプラインとの連携が王道だ。マージをトリガーに Actions を起動する、リリースノートを自動生成して Releases に投稿する、Issue や PR をルールに沿って自動でラベリング・アサインする——開発ワークフローの定型作業を機械化できる。

レート制限という現実

つまずきの大半はレート制限だ。認証ありでも 1 時間あたりの上限があり、GraphQL は別途「クエリの複雑さ」に応じた予算が課される。大量データを扱うツールでは、ETag を使った条件付きリクエストでキャッシュを効かせ、必要な分だけ取る設計が欠かせない。

費用面では、パブリックリポジトリの操作は無料で、プライベートリポジトリは GitHub のプランに依存する。API 利用そのものに追加課金はない。当然ながら GitLab や Bitbucket のリポジトリは操作できず、それらは各プラットフォームの API を使うことになる。

認証方式で使える枠が変わる

GitHub API のレート制限は認証方式によって大きく異なる。未認証は極端に低く、個人アクセストークンで実用域になり、GitHub App としてインストールすると更に有利な枠が与えられる。組織で継続的に使う仕組みを作るなら、個人トークンではなく GitHub App にしておくほうが、枠の面でも権限管理の面でも後が楽になる。個人トークンは発行した個人が退職すると止まる、という運用上の弱点もある。

💡
大量取得は GraphQL で呼び出し回数を畳めます

REST で「リポジトリ一覧を取り、各リポジトリのイシューを取り、各イシューのコメントを取る」と呼び出し回数が掛け算で増えます。GraphQL なら必要な階層を一度に取れるため、レート制限に対して圧倒的に有利です。ただし GraphQL 側はクエリの複雑さでコストが計算される点は把握しておいてください。

Webhook と組み合わせる

リポジトリの変化を追いたい場合、API をポーリングするとレート制限をすぐ使い切る。Webhook でイベントを受け取り、必要なときだけ API で詳細を取得する構成が基本になる。CI 連携や自動レビューのような仕組みは、この組み合わせを前提に設計されている。