---
title: "GitHub APIの使い方：REST・GraphQLの認証とレート制限、Issue・PR操作の実装【2026年11月】"
url: "https://www.issoh.co.jp/tech/details/19972/"
published: 2026-11-18
updated: 2026-11-18
categories: ["開発"]
publisher: "株式会社一創"
---

# GitHub APIの使い方：REST・GraphQLの認証とレート制限、Issue・PR操作の実装【2026年11月】

GitHub APIは、リポジトリ・Issue・Pull Request・Actionsなど、GitHub上のほぼすべての操作をプログラムから行うためのAPIです。夜間バッチが失敗したらIssueを起票する、週次でレビュー待ちのPull Requestを集計して通知する、といった社内の自動化はこのAPIで組みます。この記事では、REST APIとGraphQL APIの使い分け、PAT・GITHUB\_TOKEN・GitHub Appの認証の選び方、curlとOctokitでのIssue・PR操作のコード、レート制限の数値と403・429の待ち方を、2026年11月時点の公式ドキュメントに沿って整理しました。2026-03-10版のAPIバージョンで変わった点も扱います。

## まとめ：GitHub APIを業務の自動化に組み込むときの認証と版指定の勘所

まず決めるのは認証です。個人の検証や単発のスクリプトならfine-grained PAT、GitHub Actionsの中なら`GITHUB_TOKEN`、組織で常駐させる連携ならGitHub Appを選びます。退職や異動で止まらない連携にしたいなら、最初からGitHub Appで作るほうが後の手戻りが少なく済みます。

実装では4つの事実を押さえれば大きく外しません。リクエストには`X-GitHub-Api-Version`を付け、新規実装は2026-03-10版で書く。一覧取得は`per_page=100`と`link`ヘッダーでページを送る。Issue一覧にはPull Requestも混ざる。レート制限は認証ユーザーで1時間5,000回、Actions内の`GITHUB_TOKEN`は1リポジトリ1,000回で、作成系は1分80件の別枠がある。ghコマンドで書ける程度の処理は自前で組まず、業務データとの突き合わせが要る連携だけをコードにします。

## GitHub APIの全体像と、REST・GraphQLの使い分けとAPIバージョンの前提

GitHub APIにはREST APIとGraphQL APIの2系統があり、認証とレート制限の数え方が異なります。どちらで書くかを先に決めておくと、後からの書き直しを避けられます。

### REST APIのapi.github.comとGraphQLの単一エンドポイントの違い

REST APIは`https://api.github.com/repos/OWNER/REPO/issues`のように、リソースごとにURLが分かれています。GraphQL APIは`https://api.github.com/graphql`の1本だけで、取りたい項目をクエリで指定します。

使い分けの基準は単純です。1件の作成・更新や、Webhookを受けてから1つの操作を返すだけならREST。複数のPull Requestについてレビュー状態と作成者をまとめて取りたいなど、RESTだと何十回も呼ぶ集計ならGraphQLを選びます。GraphQLそのものの書き方は[GraphQLとは？REST APIとの違いとクエリ・リゾルバの書き方](https://www.issoh.co.jp/tech/details/2924/)で解説しています。迷ったらRESTで書き始め、呼び出し回数がレート制限に響いた部分だけGraphQLに置き換えれば十分です。

### X-GitHub-Api-Versionヘッダーと2026-03-10版で変わった項目

REST APIは日付でバージョンを管理しています。[API Versionsのページ](https://docs.github.com/en/rest/about-the-rest-api/api-versions)によると、2026年11月時点でサポートされているのは`2026-03-10`と`2022-11-28`の2つです。ヘッダーを省略すると`2022-11-28`として扱われ、この版のサポート終了日は2028年3月10日と告知されています。

新しい版で何が変わったかは[Breaking changesのページ](https://docs.github.com/en/rest/about-the-rest-api/breaking-changes)に一覧があります。既存のスクリプトを2026-03-10版へ上げるときに影響しやすいのは、次の4点です。

- Pull Requestのレスポンスから`merge_commit_sha`が消えた
- Issueなどの単数の`assignee`が消え、`assignees`配列だけになった
- `GET /rate_limit`の`rate`が消え、`resources.core`から読む形になった
- workflow\_dispatchの起動APIが204ではなく200で実行の詳細を返すようになった

新規に書くコードは2026-03-10を明示します。古いスクリプトはヘッダーを付けていなければ2022-11-28で動き続けるため、2028年3月までに上の項目を読んでいる箇所を洗い出しておけば移行できます。

## 認証方式の選び方：PAT・GITHUB\_TOKEN・GitHub Appを用途で分ける基準

認証方式で、操作できる範囲・レート制限の上限・人が辞めたときの影響が決まります。用途ごとの選び方は次の表のとおりです。

| 方式               | 向く用途         | REST上限（時）       | 期限       |
| ---------------- | ------------ | --------------- | -------- |
| fine-grained PAT | 個人の検証・単発処理   | 5,000回          | 作成時に指定   |
| GITHUB\_TOKEN    | Actionsのジョブ内 | 1,000回（リポジトリ単位） | ジョブ終了まで  |
| GitHub App       | 組織の常駐連携      | 5,000〜12,500回   | 1時間（再発行） |

数値は[Rate limits for the REST APIのページ](https://docs.github.com/en/rest/using-the-rest-api/rate-limits-for-the-rest-api)の値で、GitHub Enterprise Cloudの組織が持つGitHub Appは1時間15,000回まで上がります。

### 個人の検証はfine-grained PAT、組織の常駐連携はGitHub App

PATはユーザー本人の権限で動くため、作った人がOrganizationを抜けると連携ごと止まります。検証用ならこれで困りません。トークンの作り方やclassicとの違いは[GitHub PATとは？作成方法・classicとfine-grainedの違い](https://www.issoh.co.jp/tech/details/7545/)にまとめています。

GitHub Appは組織にインストールされる独立した主体で、ユーザーの在籍に左右されません。リポジトリ数やユーザー数が20を超えると上限が1つにつき50回ずつ加算され、最大12,500回まで伸びる点もPATとの差です。Actionsの中で完結する処理なら`GITHUB_TOKEN`で足り、付与する権限は[GitHub Actionsのpermissionsの記事](https://www.issoh.co.jp/tech/details/16937/)の手順で最小に絞ります。

### GitHub AppのJWTからインストールトークンを取る手順と期限

GitHub Appで呼び出すには2段階の手順が要ります。まずAppの秘密鍵でJWTを署名し、そのJWTで発行してもらうのが、インストール単位のアクセストークンです。[JWTの生成手順](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-json-web-token-jwt-for-a-github-app)では、署名はRS256、`iat`は時計のずれに備えて60秒前、`exp`は10分以内、`iss`にはクライアントIDを入れるよう求めています。

```
# pip install PyJWT cryptography requests
import os, time
import jwt, requests

with open(os.environ["GH_APP_KEY_PATH"]) as f:
    private_key = f.read()

now = int(time.time())
app_jwt = jwt.encode(
    {"iat": now - 60, "exp": now + 540, "iss": os.environ["GH_APP_CLIENT_ID"]},
    private_key, algorithm="RS256")

# インストールIDはApp設定画面か GET /repos/OWNER/REPO/installation で確認する
inst_id = os.environ["GH_APP_INSTALLATION_ID"]
res = requests.post(
    f"https://api.github.com/app/installations/{inst_id}/access_tokens",
    headers={"Accept": "application/vnd.github+json",
             "Authorization": f"Bearer {app_jwt}",
             "X-GitHub-Api-Version": "2026-03-10"},
    # 対象リポジトリと権限を絞ると、漏えい時の影響範囲が狭まる
    json={"repositories": ["REPO"], "permissions": {"issues": "write"}})
res.raise_for_status()
token = res.json()["token"]  # 有効期限は1時間
```

[インストールトークンの発行手順](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-an-installation-access-token-for-a-github-app)によると、トークンは1時間で失効し、`repositories`は最大500件まで指定できます。同じページには注意書きもあり、2026年4月27日から新しい形式のトークンが段階的に発行中です。トークンを40文字固定と決め打ちして検証しているコードは、ここで壊れます。

## curlとOctokitでIssue・Pull Requestを操作する実装手順と確認方法

ここからは、障害時のIssue起票、Issue一覧の取得、Pull Requestへのコメント、レビュー状況の集計を順にコードで書きます。トークンは環境変数`GITHUB_TOKEN`に入っている前提です。

### curlでIssueを作成し、レスポンスヘッダーで残り回数を確かめる

最小の確認はcurlで足ります。`-i`を付けるとレスポンスヘッダーも表示されるので、レート制限の残りを同時に見られます。

```
curl -i -X POST \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer $GITHUB_TOKEN" \
  -H "X-GitHub-Api-Version: 2026-03-10" \
  https://api.github.com/repos/OWNER/REPO/issues \
  -d '{"title":"夜間バッチ失敗：受注取込","body":"ジョブID 1234 が終了コード1で停止","labels":["batch"]}'

# 応答ヘッダーの例（値は環境により異なる）
# x-ratelimit-limit: 5000
# x-ratelimit-remaining: 4987
# x-ratelimit-reset: 1795000000   ← UTCのエポック秒
```

成功すると201が返り、本文の`number`が採番されたIssue番号です。`x-ratelimit-resource`を見ると、そのリクエストがどの枠に数えられたかも分かります。ラベルに存在しない名前を渡すと新しく作られてしまうため、運用では既存ラベル名を定数で持たせます。

### Octokit 5系でIssue一覧をページ送りし、PRへコメントする例

Node.jsでは公式SDKの[octokit.js](https://github.com/octokit/octokit.js)を使います。npmの`octokit`は2026年11月時点で5.0系、Node.js 20以上が必要で、ページ送り・スロットリング・リトライのプラグインを同梱しています。

```
// npm install octokit
import { Octokit } from "octokit";

const octokit = new Octokit({ auth: process.env.GITHUB_TOKEN });
const headers = { "X-GitHub-Api-Version": "2026-03-10" };

// link ヘッダーを辿って全ページを取得する
const items = await octokit.paginate(octokit.rest.issues.listForRepo, {
  owner: "OWNER", repo: "REPO", state: "open", per_page: 100, headers,
});

// Issue一覧にはPull Requestも含まれるので pull_request キーで分ける
const issues = items.filter((i) => !i.pull_request);
const pulls = items.filter((i) => i.pull_request);
console.log(`Issue ${issues.length}件 / PR ${pulls.length}件`);

// PRの会話欄へのコメントは Issue のコメントAPIで書く
await octokit.rest.issues.createComment({
  owner: "OWNER", repo: "REPO", issue_number: pulls[0].number,
  body: "ステージング環境へのデプロイが完了しました", headers,
});
```

[ページネーションのページ](https://docs.github.com/en/rest/using-the-rest-api/using-pagination-in-the-rest-api)によると、`per_page`の上限は多くのエンドポイントで100で、それを超えて指定してもエラーにならず黙って100に丸められます。件数が合わないときにまず疑うのは、ページ送りの漏れです。Issueと[Pull RequestのAPI](https://docs.github.com/en/rest/pulls/pulls)の関係は[Issues APIのページ](https://docs.github.com/en/rest/issues/issues)に「すべてのPull RequestはIssueとして扱われる」と書かれており、集計スクリプトでPRを数え込む事故の原因になります。

### GraphQLでPRのレビュー状況を1回のクエリで集める書き方

「開いているPull Requestの番号・作成者・レビュー判定」をRESTで集めると、PRごとにレビューAPIを呼ぶため件数分だけリクエストが増えます。GraphQLなら1回で済みます。

```
const { repository, rateLimit } = await octokit.graphql(`
  query ($owner: String!, $repo: String!) {
    repository(owner: $owner, name: $repo) {
      pullRequests(states: OPEN, first: 50) {
        nodes { number title reviewDecision author { login } }
      }
    }
    rateLimit { cost remaining resetAt }
  }`, { owner: "OWNER", repo: "REPO" });

// reviewDecision は APPROVED / CHANGES_REQUESTED / REVIEW_REQUIRED のいずれか
const waiting = repository.pullRequests.nodes
  .filter((pr) => pr.reviewDecision === "REVIEW_REQUIRED");
console.log(waiting.map((pr) => `#${pr.number} ${pr.title}`), rateLimit);
```

[GraphQLの制限のページ](https://docs.github.com/en/graphql/overview/rate-limits-and-query-limits-for-the-graphql-api)では、`first`と`last`は1〜100、1回で要求できるノードは合計500,000までと決められています。`rateLimit { cost }`をクエリに入れておくと、そのクエリが何ポイント消費したかを毎回記録できます。

## レート制限の数値と、403・429を受けたときに待つ時間の決め方

GitHub APIの制限は、1時間単位の「プライマリ」と、短時間の集中を抑える「セカンダリ」の二重構造です。レート制限一般の設計は[APIレート制限とは？5方式の比較と429設計](https://www.issoh.co.jp/tech/details/16179/)で扱っており、ここではGitHub固有の数値と待ち方に絞ります。

### プライマリ制限は毎時5,000回、ActionsのGITHUB\_TOKENは1,000回

未認証のリクエストはIPアドレスあたり1時間60回しかありません。社内ネットワークから複数のスクリプトが未認証で叩くと、同じ出口IPで枠を分け合ってすぐ尽きます。認証すればユーザーあたり5,000回、GraphQLは別枠で、1時間あたりの上限が5,000ポイントに設定されています。

見落としやすいのはActionsです。`GITHUB_TOKEN`は1リポジトリにつき1時間1,000回で、マトリックスビルドの各ジョブからAPIを呼ぶ構成だと上限に届きます。上限に達すると403か429が返り、`x-ratelimit-remaining`が0になるので、`x-ratelimit-reset`の時刻まで再試行しないのが公式の指示です。

### セカンダリ制限の同時100件・作成系80件毎分を超えない設計

セカンダリ制限は事前に残量を確かめる手段がありません。公式ページに載っている主な目安は次のとおりです。

- 同時リクエストはRESTとGraphQLの合計で100件まで
- RESTは1分900ポイント、GraphQLは1分2,000ポイントまで（GETは1、POSTやPATCHは5ポイント）
- Issueやコメントなどの作成は1分80件、1時間500件まで

過去分のIssueを一括移行するような処理は、この作成系の上限で止まります。1件ごとに1秒以上空けて直列で投げれば、80件/分を超えません。制限にかかったときの待ち方は、`retry-after`ヘッダーがあればその秒数、無ければ`x-ratelimit-reset`まで、どちらも無ければ最低1分待ち、それでも失敗すれば待ち時間を指数的に延ばす、という順です。制限中に叩き続けると連携自体が禁止される場合があると明記されているので、即時リトライのループは書きません。

## 自前でAPI連携を組むか、ghやActionsで済ませるかの判断基準

GitHub APIは何でもできる反面、自前のコードは認証情報の管理とバージョン追従の保守を背負います。どこまでを既製の道具で済ませるかを先に線引きします。

### ghコマンドやgithub-scriptで足りる場面と自前実装が要る場面

処理がGitHubの中で閉じているなら、自前のアプリは作りません。手元やcronからの単発操作は`gh api repos/OWNER/REPO/issues`のようにghコマンドで書け、認証とページ送りもghが受け持ちます（[ghコマンド（GitHub CLI）の使い方](https://www.issoh.co.jp/tech/details/3547/)）。PRやIssueのイベントをきっかけにした処理なら、[actions/github-scriptの使い方](https://www.issoh.co.jp/tech/details/6529/)のとおりワークフローの中にJavaScriptで書けば、トークンの保管場所も要りません。

自前実装が要るのは、GitHubの外にある業務データと突き合わせる場合です。障害管理システムのチケットとIssueを双方向で同期する、受注システムの案件番号でPRを検索して進捗を顧客向け画面に出す、といった連携がこれにあたります。この線を越えるかどうかが、外部のサーバーとGitHub Appを用意するかの分かれ目です。

### GitHub Appへ移すべき条件と、PATのまま運用すると詰まる失敗例

次のどれかに当てはまったら、PATをやめてGitHub Appへ移します。連携が1年以上動き続ける予定がある。複数のリポジトリや複数の部署にまたがる。1時間5,000回を超えそうな集計がある。どれも当てはまらない検証用スクリプトにGitHub Appを用意するのは過剰です。

よくある失敗は、担当者個人のPATで本番連携を動かし、その人の異動や有効期限切れで夜間のIssue起票が止まり、数日気づかないパターンです。PATで動いている処理は、誰のトークンか・期限はいつかを台帳に残すだけでも事故を減らせます。GitHub Actionsを含めたCI/CD全体の設計からまとめて見直したい場合は、[DevOps・CI/CD導入支援](https://www.issoh.co.jp/service/system/devops/)でGitHub Appの設計と権限の棚卸しからお手伝いしています。

## よくある質問

GitHub APIを使い始めるときによく出る疑問をまとめました。

### GitHub APIは無料で使えますか？

APIの呼び出し自体に料金はかかりません。Freeプランのアカウントでも、認証すれば1時間5,000回まで呼べます。ただしAPIで操作する先の機能には料金が絡むものがあり、たとえばAPIからGitHub Actionsのワークフローを起動すれば、その実行時間はActionsの課金対象です。上限を引き上げたい場合は、GitHub Enterprise Cloudの組織が持つGitHub Appにすると1時間15,000回まで広がります。

### GitHub APIのトークンはどこで取得しますか？

個人で使うならGitHubの設定画面の「Developer settings」からfine-grained personal access tokenを作ります。発行時には対象リポジトリと権限を絞り、期限の設定も必須です。組織の連携ならGitHub Appを作成して秘密鍵を発行し、JWT経由でインストールトークンを取ります。Actionsの中では自動で発行される`GITHUB_TOKEN`が使えるため、自分でトークンを作る必要はありません。

### 403エラーが返るのはレート制限が原因ですか？

403はレート制限と権限不足の両方で返るため、ヘッダーで切り分けます。`x-ratelimit-remaining`が0ならプライマリ制限、`retry-after`が付いていればセカンダリ制限です。どちらでもなければ、トークンの権限不足か、Organizationの設定でPATのアクセスが制限されている可能性があります。fine-grained PATはOrganization側の承認が要る設定になっている場合があり、その状態では読み取りも拒否されます。

### GitHubのWebhookとAPIはどう使い分けますか？

APIはこちらから取りに行く仕組み、Webhookは何か起きたときにGitHubから通知が来る仕組みです。PRが作られたら何かする、という処理を定期的なAPI呼び出しで監視すると、レート制限を無駄に消費します。イベントはWebhookで受け、受けた後の追加情報の取得や書き込みにAPIを使う組み合わせが基本形です。受信側の署名検証と冪等性は[Webhookの作り方と実装方法](https://www.issoh.co.jp/tech/details/1378/)で解説しています。

### GitLabのAPIと同じ作りで書けますか？

RESTで個人トークンを付けて呼ぶ基本は同じですが、細部は異なります。GitHubは`X-GitHub-Api-Version`で日付版を指定し、PRとIssueの番号体系は共通です。GitLabはURLに`/api/v4`を含み、マージリクエストはIssueと別の番号を持ちます。両方に対応するツールを作る場合に保守しやすいのは、共通のインターフェースを切って製品ごとにアダプタを書く構成です。GitLab側の実装は[GitLab APIの使い方](https://www.issoh.co.jp/tech/details/19681/)にまとめています。

## 関連記事

- [GitHub PAT（Personal Access Token）とは？作成方法・classicとfine-grainedの違い・確認と失効【2026年10月】](https://www.issoh.co.jp/tech/details/7545/)：API呼び出しに使うトークンの作成手順と権限の選び方です。
- [ghコマンド（GitHub CLI）とは？インストール方法と使い方・コマンド一覧【v2.102対応】](https://www.issoh.co.jp/tech/details/3547/)：コードを書かずにAPIを叩けるgh apiを含むコマンド全般です。
- [actions/github-scriptの使い方｜v9対応の書き方・入力一覧・PR自動化の実例](https://www.issoh.co.jp/tech/details/6529/)：ワークフローの中からOctokitでAPIを呼ぶ書き方です。
- [GitHubのPull Requestの作り方：作成手順とマージ方式・レビュー必須化の決め方](https://www.issoh.co.jp/tech/details/18004/)：APIで操作するPull Requestの機能と運用ルールです。
- [GitHub Issueとは？使い方・書き方と運用のベストプラクティス【2026年版】](https://www.issoh.co.jp/tech/details/5898/)：APIで起票するIssueの書き方とラベル運用です。

---

出典: [GitHub APIの使い方：REST・GraphQLの認証とレート制限、Issue・PR操作の実装【2026年11月】](<https://www.issoh.co.jp/tech/details/19972/>)（株式会社一創）
