用意するもの

使う言語と手法によって、必要なものが変わる。自分が読む回の分だけ用意すればよい。

もの使う回備考
GitHub アカウントトークンを使う場合公開リポジトリをトークンなしで試すだけなら不要
Python 3.10 以上PART 03〜05ライブラリは各回で pip install する
Git(Git for Windows)PART 05・07git --version で確認する
GitHub CLI(gh)PART 04使う場合だけ
Excel(Windows 版)PART 06・0732bit 版・64bit 版のどちらでもよい
Google アカウントPART 08Google スプレッドシートと Apps Script を使う

アクセストークンを発行する

トークンは2種類ある

API の認証には、パスワードの代わりに Personal Access Token(個人用アクセストークン) を使う。トークンには2種類ある。

種類先頭の文字権限の決め方評価
fine-grained(きめ細かいトークン)github_pat_対象のリポジトリを選び、操作の種類ごとに「読み取り」「読み書き」を決めるこのシリーズで使う。読み取り専用にできる
classic(従来のトークン)ghp_repo などのスコープ単位。repo を付けると、アクセスできる全リポジトリの読み書きが可能になるfine-grained が使えない場合だけ使う

コミット履歴を読むだけなら、書き込みの権限は要らない。漏れたときの被害を小さくするために、fine-grained トークンを読み取り専用で発行する。

発行の手順

  1. GitHub にサインインし、右上のアイコンから Settings を開く
  2. 左のメニューの一番下にある Developer settings をクリックする
  3. Personal access tokens → Fine-grained tokens → Generate new token の順にクリックする
  4. Token name に用途がわかる名前を入れる(例:commit-history-readonly)
  5. Expiration で有効期限を選ぶ。短いほど安全で、期限が来たら再発行する
  6. Repository access で対象を選ぶ(下の表を参照)
  7. プライベートリポジトリを読む場合は、Permissions の Repository permissions で Contents を Read-only にする(Metadata は自動で Read-only になる)
  8. Generate token をクリックし、表示されたトークンをコピーする
Repository access の選択肢使いどころ
Public repositories公開リポジトリを読むだけ。権限の追加は不要。このシリーズのサンプルを動かすならこれで足りる
Only select repositoriesプライベートリポジトリを読む。対象を1つずつ選ぶ(おすすめ)
All repositories自分が持つすべてのリポジトリ。対象が多く、今後も増える場合だけ使う

⚠️ トークンは発行直後の1回しか表示されない

画面を閉じると二度と確認できない。コピーしそこねたら、削除して発行し直す。トークンはパスワードと同じ扱いをし、チャットやメールに貼らない。画面の表記や項目の並びは変わることがあるので、見当たらない項目は公式ドキュメントで確認する。

トークンを保管する

トークンをコードに直接書くと、そのコードをリポジトリに入れた時点で漏れる。コードとは別の場所に置き、実行時に読み込むのが原則だ。

実行環境保管場所読み込み方
Pythonユーザー環境変数 GITHUB_TOKENos.environ.get("GITHUB_TOKEN")
Excel VBAユーザー環境変数 GITHUB_TOKENEnviron$("GITHUB_TOKEN")
Google Apps Scriptスクリプト プロパティ GITHUB_TOKENPropertiesService.getScriptProperties()(PART 08)
GitHub CLICLI が管理する(gh auth login)自分で扱わない(PART 04)

Windows でユーザー環境変数を設定するには、スタートメニューで「環境変数」と検索して 「環境変数を編集」 を開き、ユーザー環境変数の「新規」で変数名 GITHUB_TOKEN と値を入力する。PowerShell から設定する場合は次のとおりだ。

PowerShell
# ユーザー環境変数に保存する(値は自分のトークンに置き換える)
[Environment]::SetEnvironmentVariable("GITHUB_TOKEN", "github_pat_xxxxxxxx", "User")

設定した値は、設定後に起動したアプリから見える。すでに開いているターミナルや Excel には反映されないので、開き直す。

💡 漏れたと思ったらすぐ失効させる

トークンの一覧画面(Fine-grained tokens)で対象を選び、Delete または Regenerate で無効にできる。なお、GitHub のトークンを公開リポジトリにプッシュすると、GitHub が検知して自動的に失効させることがある。

接続を確認する

まずトークンなしで、お題のリポジトリの最新コミットを1件取得する。Windows の PowerShell では、curl が別のコマンドの別名になっていることがあるので curl.exe と書く。

PowerShell(トークンなし)
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 が返れば成功だ。次に、トークンを付けて自分のレート制限を確認する。

PowerShell(トークンあり)
$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 rate
実行結果の例
limit used remaining      reset
----- ---- ---------      -----
 5000    0      5000 1794448800

limit が 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-limit1時間の上限(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 を呼び、ページネーションや絞り込みを含めてコミット履歴を取得する。

→ PART 03 — PythonでREST APIを呼ぶ(requests)へ