用意するもの
使う言語と手法によって、必要なものが変わる。自分が読む回の分だけ用意すればよい。
| もの | 使う回 | 備考 |
|---|---|---|
| GitHub アカウント | トークンを使う場合 | 公開リポジトリをトークンなしで試すだけなら不要 |
| Python 3.10 以上 | PART 03〜05 | ライブラリは各回で pip install する |
| Git(Git for Windows) | PART 05・07 | git --version で確認する |
GitHub CLI(gh) | PART 04 | 使う場合だけ |
| Excel(Windows 版) | PART 06・07 | 32bit 版・64bit 版のどちらでもよい |
| Google アカウント | PART 08 | Google スプレッドシートと Apps Script を使う |
アクセストークンを発行する
トークンは2種類ある
API の認証には、パスワードの代わりに Personal Access Token(個人用アクセストークン) を使う。トークンには2種類ある。
| 種類 | 先頭の文字 | 権限の決め方 | 評価 |
|---|---|---|---|
| fine-grained(きめ細かいトークン) | github_pat_ | 対象のリポジトリを選び、操作の種類ごとに「読み取り」「読み書き」を決める | このシリーズで使う。読み取り専用にできる |
| classic(従来のトークン) | ghp_ | repo などのスコープ単位。repo を付けると、アクセスできる全リポジトリの読み書きが可能になる | fine-grained が使えない場合だけ使う |
コミット履歴を読むだけなら、書き込みの権限は要らない。漏れたときの被害を小さくするために、fine-grained トークンを読み取り専用で発行する。
発行の手順
- GitHub にサインインし、右上のアイコンから Settings を開く
- 左のメニューの一番下にある Developer settings をクリックする
- Personal access tokens → Fine-grained tokens → Generate new token の順にクリックする
- Token name に用途がわかる名前を入れる(例:
commit-history-readonly) - Expiration で有効期限を選ぶ。短いほど安全で、期限が来たら再発行する
- Repository access で対象を選ぶ(下の表を参照)
- プライベートリポジトリを読む場合は、Permissions の Repository permissions で Contents を Read-only にする(Metadata は自動で Read-only になる)
- Generate token をクリックし、表示されたトークンをコピーする
| Repository access の選択肢 | 使いどころ |
|---|---|
| Public repositories | 公開リポジトリを読むだけ。権限の追加は不要。このシリーズのサンプルを動かすならこれで足りる |
| Only select repositories | プライベートリポジトリを読む。対象を1つずつ選ぶ(おすすめ) |
| All repositories | 自分が持つすべてのリポジトリ。対象が多く、今後も増える場合だけ使う |
⚠️ トークンは発行直後の1回しか表示されない
画面を閉じると二度と確認できない。コピーしそこねたら、削除して発行し直す。トークンはパスワードと同じ扱いをし、チャットやメールに貼らない。画面の表記や項目の並びは変わることがあるので、見当たらない項目は公式ドキュメントで確認する。
トークンを保管する
トークンをコードに直接書くと、そのコードをリポジトリに入れた時点で漏れる。コードとは別の場所に置き、実行時に読み込むのが原則だ。
| 実行環境 | 保管場所 | 読み込み方 |
|---|---|---|
| Python | ユーザー環境変数 GITHUB_TOKEN | os.environ.get("GITHUB_TOKEN") |
| Excel VBA | ユーザー環境変数 GITHUB_TOKEN | Environ$("GITHUB_TOKEN") |
| Google Apps Script | スクリプト プロパティ GITHUB_TOKEN | PropertiesService.getScriptProperties()(PART 08) |
| GitHub CLI | CLI が管理する(gh auth login) | 自分で扱わない(PART 04) |
Windows でユーザー環境変数を設定するには、スタートメニューで「環境変数」と検索して 「環境変数を編集」 を開き、ユーザー環境変数の「新規」で変数名 GITHUB_TOKEN と値を入力する。PowerShell から設定する場合は次のとおりだ。
# ユーザー環境変数に保存する(値は自分のトークンに置き換える)
[Environment]::SetEnvironmentVariable("GITHUB_TOKEN", "github_pat_xxxxxxxx", "User")設定した値は、設定後に起動したアプリから見える。すでに開いているターミナルや Excel には反映されないので、開き直す。
💡 漏れたと思ったらすぐ失効させる
トークンの一覧画面(Fine-grained tokens)で対象を選び、Delete または Regenerate で無効にできる。なお、GitHub のトークンを公開リポジトリにプッシュすると、GitHub が検知して自動的に失効させることがある。
接続を確認する
まずトークンなしで、お題のリポジトリの最新コミットを1件取得する。Windows の PowerShell では、curl が別のコマンドの別名になっていることがあるので curl.exe と書く。
curl.exe -s -H "Accept: application/vnd.github+json" -H "X-GitHub-Api-Version: 2022-11-28" "https://api.github.com/repos/VBA-tools/VBA-JSON/commits?per_page=1""sha": "06b6c45a..." で始まる JSON が返れば成功だ。次に、トークンを付けて自分のレート制限を確認する。
$headers = @{
Accept = "application/vnd.github+json"
"X-GitHub-Api-Version" = "2022-11-28"
Authorization = "Bearer $env:GITHUB_TOKEN"
}
Invoke-RestMethod "https://api.github.com/rate_limit" -Headers $headers |
Select-Object -ExpandProperty ratelimit used remaining reset
----- ---- --------- -----
5000 0 5000 1794448800limit が 5000 になっていれば、トークンが正しく認識されている。60 のままなら、環境変数が読めていない(ターミナルを開き直していない)か、ヘッダーの書き方が違う。401(Bad credentials)が返る場合は、トークンの値が間違っているか、期限が切れている。
レート制限を理解する
GitHub の API には、一定時間に呼べる回数の上限(レート制限)がある。
| 呼び方 | 上限 | 数える単位 |
|---|---|---|
| トークンなし | 1時間 60回 | 送信元の IP アドレス。社内から同じ IP で出ていく場合は、全員で共有する |
| Personal Access Token あり | 1時間 5,000回 | ユーザー。同じユーザーのトークンを複数使っても合算される |
| GraphQL API(トークン必須) | 1時間 5,000ポイント | 問い合わせの内容に応じてポイントを消費する(PART 04) |
残り回数は、すべてのレスポンスのヘッダーで確認できる。
| ヘッダー | 意味 |
|---|---|
x-ratelimit-limit | 1時間の上限(60 または 5000) |
x-ratelimit-remaining | 残り回数 |
x-ratelimit-used | 使った回数 |
x-ratelimit-reset | 残り回数が元に戻る時刻(UNIX 時間・UTC の秒) |
上限を超えると、ステータス 403 または 429 が返り、x-ratelimit-remaining が 0 になる。この場合は x-ratelimit-reset の時刻まで待つしかない。これとは別に、短時間に大量のリクエストを送ると「セカンダリレート制限」に当たることがあり、そのときは retry-after ヘッダーに待つべき秒数が入る。
先ほど使った /rate_limit は、呼んでも回数を消費しない。残りが気になるときはいつ確認してもよい。
💡 回数を節約するコツ
- 1ページの件数を最大(
per_page=100)にして、ページ数を減らす since・until・pathなどの条件で、取得する範囲を絞る- コミットごとの変更行数が必要なら、GraphQL かローカル方式を検討する(REST API はコミット1件につき1回かかる)
API のバージョンを指定する
GitHub の REST API は日付でバージョンが付いていて、X-GitHub-Api-Version ヘッダーで指定する。執筆時点(2026年11月)で使えるのは次の2つだ。
| バージョン | 状態 |
|---|---|
2022-11-28 | ヘッダーを省略したときの既定。2028年3月10日までサポートされる |
2026-03-10 | 最新。一部の API に互換性のない変更が入っている |
このシリーズのコードは 2022-11-28 を定数にして指定している。コミット一覧の取得は、どちらを指定しても同じ結果が返ることを確認した。ヘッダーを省略しても動くが、省略すると既定のバージョンが切り替わったときに挙動が変わるおそれがあるので、明示しておく。サポート終了までに、定数を新しいバージョンに書き換えて動作を確かめればよい。
プライベートリポジトリの場合
🔒 プライベートリポジトリを読むための設定
- トークンが必須になる。Repository access で対象のリポジトリを選び、Permissions の Contents を Read-only にする
- 組織(Organization)が持つリポジトリの場合は、トークン作成画面の Resource owner で組織を選ぶ。組織の設定によっては、管理者の承認を受けるまでトークンが使えない
- 組織が fine-grained トークンを許可していない場合は、classic トークンに
repoスコープを付けて使う。SAML シングルサインオンを使っている組織では、トークンの一覧で Configure SSO から組織を承認する - 権限がないリポジトリを指定すると、
403ではなく404(Not Found) が返る。リポジトリの存在を知らせないための仕様で、「名前の打ち間違い」と「権限不足」が同じ見え方になる点に注意する
ローカル方式でプライベートリポジトリをクローンするときの認証は、PART 05 で説明する。
✅ 次の記事では…
PART 03 では、Python の requests で REST API を呼び、ページネーションや絞り込みを含めてコミット履歴を取得する。