GitHub - API

概要

GitHub APIは、GitHubのデータやサービスにプログラムからアクセスするためのインターフェースである。

GitHub APIには2種類のAPIが提供されている。

GitHub APIの種類

種類	説明
REST API	ベースURL: https://api.github.com/ HTTPメソッド (GET、POST、PATCH、PUT、DELETE) を使用してリソースを操作する。 シンプルなリクエスト・レスポンスモデルで、幅広い用途に対応する。
GraphQL API	エンドポイント: https://api.github.com/graphql 必要なデータのみを指定して取得できる柔軟なクエリ言語を使用する。 複数リソースのデータを1回のリクエストで取得できるため、オーバーフェッチを防止できる。

両APIとも認証が必要な操作と不要な操作があるが、認証を行うことでレート制限が緩和され、プライベートリポジトリにもアクセス可能になる。

認証

GitHub APIの認証方式は複数存在する。
用途に応じて適切な認証方式を選択する。

Personal Access Token

Personal Access Token (PAT) は、個人のGitHubアカウントの代わりにAPIリクエストを認証するためのトークンである。

PATには2種類ある。

Fine-grained Personal Access Token (推奨)

Fine-grained PATは、より細かい権限制御が可能な新しい形式のトークンである。

• 特定のリポジトリに対してのみアクセス権を付与できる。
• 各操作 (エンドポイント) 単位で権限を設定できる。
• 有効期限の設定が必須である。
• GitHub.comの[Settings] - [Developer settings] - [Personal access tokens] - [Fine-grained tokens]から作成する。

Classic Personal Access Token

Classic PATは、従来のスコープベースのトークンである。

• repo、user、admin:org 等のスコープ単位で権限を付与する。
• 全リポジトリへのアクセスが許可されるため、Fine-grained PATより権限が広くなりやすい。
• GitHub.comの[Settings] - [Developer settings] - [Personal access tokens] - [Tokens (classic)]から作成する。

PATを使用する時は、リクエストヘッダに以下に示す形式で指定する。

Authorization: Bearer <YOUR_TOKEN>
または
Authorization: token <YOUR_TOKEN>

GitHub Apps

GitHub Appsは、GitHubプラットフォーム上に構築するアプリケーションのための認証方式である。

GitHub Appsは2段階の認証方式を使用する。

• JWT認証 (アプリ自身の認証)

  アプリのプライベートキーを使用してJWT (JSON Web Token) を生成する。

  JWTは10分間有効である。

  インストールアクセストークンの取得に使用する。

• インストールアクセストークン

  JWTを使用して POST /app/installations/{installation_id}/access_tokens に対してリクエストを送信することで取得する。

  短期間 (1時間) で自動失効する。

  実際のAPIリクエストにはインストールアクセストークンを使用する。

OAuth Apps

OAuth Appsは、ユーザの代わりにGitHub APIにアクセスするための認証方式である。

• OAuthフローを通じてユーザの認可を得る。
• ユーザアクセストークンを取得してAPIリクエストに使用する。
• GitHub AppsのOAuth機能と比較して、権限管理の粒度が粗い。
• 新規の用途には、GitHub Appsの使用が推奨される。

GITHUB_TOKEN

GITHUB_TOKEN は、GitHub Actionsワークフロー内で自動的に生成されるシークレットトークンである。

• ワークフロー実行ごとに自動生成される。
• ワークフローが完了すると自動的に失効する。
• リポジトリのActionsの設定でデフォルトの権限を調整できる。
• 外部リソースへのアクセスには別途認証が必要である。

GitHub Actionsのワークフロー内では以下に示すように使用する。

 - name: GitHub APIを呼び出す
   run: |
      curl -H "Authorization: Bearer ${{ secrets.GITHUB_TOKEN }}" \
           https://api.github.com/repos/${{ github.repository }}

認証方法の比較

下表に、各認証方式の特徴を示す。

認証方式の比較

認証方式	用途	権限の粒度	有効期限
Fine-grained PAT	個人の開発、スクリプト	リポジトリ単位・操作単位	設定必須 (最大1年)
Classic PAT	個人の開発、スクリプト	スコープ単位	設定可能 (無期限も可)
GitHub Apps	サードパーティアプリ、CI/CD	リポジトリ単位・権限単位	インストールトークンは1時間
OAuth Apps	ユーザ認可が必要なアプリ	スコープ単位	設定による
GITHUB_TOKEN	GitHub Actionsワークフロー	リポジトリ権限に準拠	ワークフロー終了まで

REST API

エンドポイントの構造

GitHub REST APIのベースURLは https://api.github.com/ である。

エンドポイントは以下の形式で構成される。

https://api.github.com/{リソースパス}

下表に、リソースパスの例を示す。

REST APIの主要なエンドポイント例

エンドポイント	説明
/repos/{owner}/{repo}	特定リポジトリの情報
/repos/{owner}/{repo}/issues	リポジトリのIssue一覧
/user	認証済みユーザの情報
/orgs/{org}	組織の情報

下表に、HTTPメソッドと操作の対応を示す。

HTTPメソッド	操作内容
GET	リソースの取得
POST	リソースの作成
PATCH	リソースの部分更新
PUT	リソースの置換・関連付け
DELETE	リソースの削除

リクエストとレスポンス

GitHub REST APIのリクエストには、以下に示すヘッダを設定することが推奨される。

主要なリクエストヘッダ

ヘッダ名	説明	例
Authorization	認証トークン	Bearer ghp_xxxxxxxxxxxx
Accept	レスポンス形式の指定	application/vnd.github+json
X-GitHub-Api-Version	APIバージョンの指定	2022-11-28
User-Agent	アプリケーション識別子	MyApp/1.0

レスポンスは、JSON形式で返される。
日時は、ISO 8601形式 (例: 2024-01-15T12:00:00Z) で表現される。

ページネーション

複数件のリソースを返すエンドポイントでは、ページネーションが使用される。

• per_page クエリパラメータでページあたりの件数を指定する。(最大100)
• page クエリパラメータでページ番号を指定する。
• レスポンスの Link ヘッダに次ページ、前ページ等のURLが含まれる。

Link ヘッダの例を以下に示す。

Link: <https://api.github.com/repos/owner/repo/issues?page=2>; rel="next",
      <https://api.github.com/repos/owner/repo/issues?page=10>; rel="last"

rel の値は next、prev、first、last の4種類がある。

主要なエンドポイント

下表に、よく使用される主要なエンドポイントを示す。

主要エンドポイント一覧

カテゴリ	メソッド	エンドポイント	説明
リポジトリ	GET	/repos/{owner}/{repo}	リポジトリ情報の取得
リポジトリ	POST	/user/repos	リポジトリの作成
リポジトリ	GET	/repos/{owner}/{repo}/contents/{path}	ファイル内容の取得
Issues	GET	/repos/{owner}/{repo}/issues	Issue一覧の取得
Issues	POST	/repos/{owner}/{repo}/issues	Issueの作成
Issues	PATCH	/repos/{owner}/{repo}/issues/{issue_number}	Issueの更新
Pull Requests	GET	/repos/{owner}/{repo}/pulls	PR一覧の取得
Pull Requests	POST	/repos/{owner}/{repo}/pulls	PRの作成
Pull Requests	PUT	/repos/{owner}/{repo}/pulls/{pull_number}/merge	PRのマージ
ユーザ	GET	/user	認証済みユーザ情報の取得
ユーザ	GET	/users/{username}	特定ユーザ情報の取得

使用例

curlを使用したREST APIのリクエスト例を以下に示す。

• リポジトリ情報の取得

   curl -L \
        -H "Accept: application/vnd.github+json" \
        -H "Authorization: Bearer <YOUR_TOKEN>" \
        -H "X-GitHub-Api-Version: 2022-11-28" \
        https://api.github.com/repos/octocat/hello-world
  

  
  

• Issueの作成

   curl -L \
        -X POST \
        -H "Accept: application/vnd.github+json" \
        -H "Authorization: Bearer <YOUR_TOKEN>" \
        -H "X-GitHub-Api-Version: 2022-11-28" \
        https://api.github.com/repos/octocat/hello-world/issues \
        -d '{"title":"バグ報告","body":"バグの詳細説明","labels":["bug"]}'
  

  
  

• Issue一覧の取得 (ページネーション使用)

   curl -L \
        -H "Accept: application/vnd.github+json" \
        -H "Authorization: Bearer <YOUR_TOKEN>" \
        -H "X-GitHub-Api-Version: 2022-11-28" \
        "https://api.github.com/repos/octocat/hello-world/issues?per_page=50&page=1"
  

GraphQL API

GraphQLとは

GraphQLは、APIのためのクエリ言語であり、必要なデータのみを指定して取得できる仕組みである。

REST APIと比較した時のGraphQL APIのメリットを以下に示す。

REST APIと比較したGraphQL APIのメリット

観点	メリット
データ取得の効率性	必要なフィールドのみを指定して取得するため、不要なデータの転送を削減できる。
リクエスト回数の削減	複数のリソースに関するデータを1回のリクエストで取得できる。
APIの明確性	型システムによりAPIの構造が明確である。
クライアントの柔軟性	クライアント側でデータ要件を柔軟に調整できる。

エンドポイント

GitHub GraphQL APIのエンドポイントは以下の1つのみである。

https://api.github.com/graphql

REST APIとは異なり、全てのリクエストは POST メソッドで送信する。
リクエストボディにJSONとしてクエリを含める。

curl -L \
     -X POST \
     -H "Authorization: Bearer <YOUR_TOKEN>" \
     -H "Content-Type: application/json" \
     https://api.github.com/graphql \
     -d '{"query": "{ viewer { login } }"}'

クエリの基本

GraphQLのクエリは、取得したいデータの構造を宣言的に記述する。

• 認証済みユーザの情報を取得するクエリの例

   {
      "query": "query { viewer { login name email } }"
   }
  

  
  

• 特定リポジトリの情報を取得するクエリの例

   {
      "query": "query { repository(owner: \"octocat\", name: \"hello-world\") { name description stargazerCount forkCount } }"
   }
  

  
  

• 横断検索 (search) を使用したクエリの例

  searchは最大1,000件の結果を返す。

   {
      "query": "query { search(query: \"repo:octocat/hello-world is:issue is:open\", type: ISSUE, first: 10) { issueCount nodes { ... on Issue { title number } } } }"
   }
  

ミューテーション

GraphQLでデータを変更する操作には、ミューテーション (mutation) を使用する。

Issueにリアクションを追加するミューテーションの例を以下に示す。

 {
    "query": "mutation { addReaction(input: {subjectId: \"MDU6SXNzdWUx\", content: THUMBS_UP}) { reaction { content } subject { id } } }"
 }

変数の使用

GraphQLでは、クエリと変数を分離して記述できる。
変数を使用することにより、クエリの再利用性が向上して、特殊文字のエスケープが不要になる。

 {
    "query": "query GetRepository($owner: String!, $name: String!) { repository(owner: $owner, name: $name) { name description stargazerCount issues(first: 5, states: OPEN) { nodes { title number } } } }",
    "variables": {
       "owner": "octocat",
       "name": "hello-world"
    }
 }

GitHub CLI (gh)

インストールと認証

GitHub CLI (gh) は、コマンドラインからGitHubの操作を行うための公式ツールである。

インストール方法を以下に示す。

# MacOS (Homebrew)
brew install gh

# RHEL
sudo dnf install gh

# SUSE
sudo zypper install gh

# Debian / Ubuntu
sudo apt install gh

インストール後、認証を行う。

# 対話的な認証フロー
gh auth login

# 認証状態の確認
gh auth status

# 環境変数を使用した認証 (CI/CD環境等)
export GH_TOKEN=<YOUR_TOKEN>

主要コマンド

下表に、GitHub CLIで使用できる主要なコマンドを示す。

GitHub CLI 主要コマンド一覧

コマンド	主なサブコマンド	説明
gh repo	create clone fork view list	リポジトリの管理
gh issue	create list view close edit	Issueの管理
gh pr	create list view merge checkout review	Pull Requestの管理
gh release	create list download view	リリースの管理
gh workflow	run list view enable disable	GitHub Actionsワークフローの管理
gh api	-	REST / GraphQL APIの直接呼び出し
gh alias	set list delete	コマンドエイリアスの管理

使用例を以下に示す。

# リポジトリのクローン
gh repo clone octocat/hello-world

# Issue一覧の表示
gh issue list --repo octocat/hello-world --state open

# Pull Requestの作成
gh pr create --title "機能追加" --body "機能の説明" --base main

# ワークフローの手動実行
gh workflow run deploy.yml --ref main

gh api

gh api コマンドを使用することにより、REST API および GraphQL APIを直接呼び出すことができる。

# REST API (GET)
gh api repos/octocat/hello-world

# REST API (POST) : Issueの作成
gh api repos/octocat/hello-world/issues \
   --method POST \
   --field title="バグ報告" \
   --field body="バグの詳細説明"

# GraphQL APIの呼び出し
gh api graphql \
   --field query='query { viewer { login name } }'

# ページネーションを自動処理して全件取得
gh api --paginate repos/octocat/hello-world/issues

エイリアス

よく使用するコマンドにエイリアスを設定することができる。

# エイリアスの設定
gh alias set prl 'pr list --state open'

# エイリアスの一覧表示
gh alias list

# エイリアスの削除
gh alias delete prl

Octokit

Octokitは、GitHub APIの公式クライアントライブラリである。

各言語向けに提供されており、APIの呼び出しを簡略化できる。

Octokit.js

Octokit.jsは、JavaScript / TypeScript向けのGitHub APIクライアントライブラリである。
Webブラウザ、Node.js、Denoの各環境で動作する。

インストール方法を以下に示す。

npm install @octokit/rest
# または
npm install octokit

基本的な使用例を以下に示す。

 import { Octokit } from "@octokit/rest";
 
 // インスタンスの作成
 const octokit = new Octokit({
    auth: "YOUR_TOKEN",
 });
 
 // リポジトリ情報の取得
 const { data: repo } = await octokit.rest.repos.get({
    owner: "octocat",
    repo: "hello-world",
 });
 console.log(repo.name);
 
 // Issueの作成
 const { data: issue } = await octokit.rest.issues.create({
    owner: "octocat",
    repo: "hello-world",
    title: "バグ報告",
    body: "バグの詳細説明",
 });
 console.log(issue.number);

ページネーションを自動処理する paginate() メソッドの使用例を以下に示す。

 // 全Issue一覧の取得 (自動ページネーション)
 const issues = await octokit.paginate(octokit.rest.issues.listForRepo, {
    owner: "octocat",
    repo: "hello-world",
    state: "open",
    per_page: 100,
 });
 
 console.log(`取得件数: ${issues.length}`);

Octokit.rb

Octokit.rbは、Ruby向けのGitHub APIクライアントライブラリである。

インストール方法を以下に示す。

gem install octokit

基本的な使用例を以下に示す。

 require "octokit"
 
 # クライアントの作成
 client = Octokit::Client.new(access_token: "YOUR_TOKEN")
 
 # リポジトリ情報の取得
 repo = client.repository("octocat/hello-world")
 puts repo.name
 
 # Issueの作成
 issue = client.create_issue("octocat/hello-world", "バグ報告", "バグの詳細説明")
 puts issue.number

Webhook

Webhookとは

WebhookはGitHub上でイベントが発生した時に、指定したURLに対してHTTP POSTリクエストを自動的に送信する仕組みである。

Webhookを使用することにより、リポジトリへのプッシュ、IssueやPull Requestの作成・更新、デプロイイベントの発生等、様々なGitHubイベントに反応した自動化を実現できる。

Webhookの設定

Webhookは、リポジトリ または Organizationの設定から作成できる。

設定項目を以下に示す。

Webhookの設定項目

項目	説明
ペイロードURL	Webhookのイベント発生時にリクエストを受信するエンドポイントのURL 公開されたHTTPSのURLである必要がある。
コンテンツタイプ	application/json (推奨) または application/x-www-form-urlencoded を選択する。
シークレット	Webhookのペイロードを検証するための秘密の文字列 設定することでHTTPリクエストの正当性を確認できる。
イベントの選択	通知を受けたいイベントを個別に選択、または、全イベントを受信するかを設定する。

イベントの種類

GitHubでは、70以上のWebhookイベントが提供されている。

下表に、主要なイベントを示す。

主要Webhookイベント

イベント名	説明
push	リポジトリへのコミットのプッシュ
pull_request	Pull Requestの作成、更新、クローズ等
issues	Issueの作成、更新、クローズ等
create	ブランチやタグの作成
delete	ブランチやタグの削除
release	リリースの公開・更新等
workflow_run	GitHub Actionsワークフローの実行
code_scanning_alert	コードスキャンアラートの検出
secret_scanning_alert	シークレットスキャンアラートの検出

シークレットによる検証

Webhookのシークレットを設定している場合、GitHubはリクエストに X-Hub-Signature-256 ヘッダを付与する。
このヘッダの値はHMAC-SHA256アルゴリズムを使用して計算されたシグネチャである。

受信側でシグネチャを検証することにより、リクエストが正当なGitHubからのものであることを確認できる。

Node.jsでの検証例を以下に示す。

 const crypto = require("crypto");
 
 function verifyWebhookSignature(payload, signature, secret) {
    const hmac = crypto.createHmac("sha256", secret);
    const digest = "sha256=" + hmac.update(payload).digest("hex");
    return crypto.timingSafeEqual(
       Buffer.from(digest),
       Buffer.from(signature)
    );
 }
 
 // Express.jsでの使用例
 app.post("/webhook", (req, res) => {
    const signature = req.headers["x-hub-signature-256"];
    const isValid = verifyWebhookSignature(
       req.rawBody,
       signature,
       process.env.WEBHOOK_SECRET
    );
 
    if (!isValid) {
       return res.status(401).send("Unauthorized");
    }
 
    // Webhookペイロードの処理
    const event = req.headers["x-github-event"];
    console.log(`イベント受信: ${event}`);
    res.status(200).send("OK");
 });

下表に、配信時に付与される主要なヘッダを示す。

Webhookリクエストの主要なHTTPヘッダ

ヘッダー	説明
X-GitHub-Event	イベントの種類 (例: push、pull_request)
X-GitHub-Delivery	配信を識別するUUID
X-Hub-Signature-256	HMAC-SHA256によるシグネチャ (シークレット設定時のみ)

ペイロードの制限

Webhookのペイロードには最大25[MB]の制限がある。

ペイロードがこの制限を超える場合、GitHubはWebhookを送信せずに、配信履歴に記録される。

大量のコミットを含むプッシュイベント等で発生する可能性があるため、注意が必要である。

GitHub Apps

GitHub Appsとは

GitHub Appsは、GitHubプラットフォーム上に構築するアプリケーションの形式であり、OAuth Appsより推奨される認証方式である。

GitHub Appsの主な特徴を以下に示す。

• Fine-grained permissionsにより、必要な権限のみを要求できる。
• 特定のリポジトリにのみインストールすることが可能である。
• ユーザの代わりではなく、アプリケーション自身として動作できる。
• SAML SSOが有効なOrganizationでは自動的に認可される。

OAuth Appsとの違い

下表に、GitHub AppsとOAuth Appsの主な違いを示す。

GitHub Apps vs OAuth Apps

比較項目	GitHub Apps	OAuth Apps
推奨度	推奨	非推奨 (新規用途)
権限の粒度	リポジトリ / 操作単位	スコープ単位
インストール単位	Organization または ユーザ	ユーザ
リポジトリの限定	特定リポジトリのみ可能	全リポジトリ対象
動作主体	アプリ自身またはユーザ	ユーザのみ
レート制限	インストールごとにスケーリング	ユーザごと
SAML SSO対応	自動認可	ユーザによる認可が必要

GitHub Appの作成

GitHub Appを新規作成する手順を以下に示す。

1. GitHub.comにログインして、[Settings]を開く。
2. 左側のサイドバーから[Developer settings]を選択する。
3. [GitHub Apps]を選択して、[New GitHub App]ボタンを押下する。
4. アプリ名、ホームページURL、Webhook URL等の必須情報を入力する。
5. 必要な権限 (Permissions) を設定する。
6. サブスクライブするイベントを選択する。
7. プライベートキーを生成してダウンロードする。

認証方式

GitHub Appsでは3種類の認証方式が提供されている。

JWT認証 (アプリ自身の認証)

アプリ自身を認証するためにJWT (JSON Web Token) を使用する。

• アプリのIDとプライベートキーを使用してJWTを生成する。
• JWTの有効期限は最大10分である。
• インストールアクセストークンの取得等、アプリレベルの操作に使用する。

 import jwt from "jsonwebtoken";
 import fs from "fs";
 
 const APP_ID = "YOUR_APP_ID";
 const PRIVATE_KEY = fs.readFileSync("private-key.pem");
 
 const payload = {
    iat: Math.floor(Date.now() / 1000) - 60,
    exp: Math.floor(Date.now() / 1000) + (10 * 60),
    iss: APP_ID,
 };
 
 const token = jwt.sign(payload, PRIVATE_KEY, { algorithm: "RS256" });

インストールアクセストークン

特定のインストールのリソースにアクセスするための短期トークンである。

• JWTを使用して POST /app/installations/{installation_id}/access_tokens に対してリクエストを送信することで取得する。
• 有効期限は1時間で、自動的に失効する。
• 特定のリポジトリやリソースへのアクセスに使用する。

ユーザアクセストークン

ユーザがGitHub Appを認可した後に取得できるトークンであり、ユーザの代わりにAPIを呼び出す場合に使用する。

レート制限

プライマリレート制限

GitHub APIには、APIの悪用を防ぐためのレート制限が設けられている。

下表に、プライマリレート制限の上限を示す。

プライマリレート制限

認証状態	上限	備考
認証なし	60リクエスト / 時間	IPアドレスごとに適用
PAT認証済み	5,000リクエスト / 時間	ユーザごとに適用
GitHub Enterprise Cloud	15,000リクエスト / 時間	Organizationメンバー
GitHub Apps (インストール)	最低5,000リクエスト / 時間	リポジトリ数に応じてスケーリング
GITHUB_TOKEN (Actions)	1,000リクエスト / 時間	リポジトリごとに適用

セカンダリレート制限

プライマリレート制限に加えて、サーバへの過負荷を防ぐためのセカンダリレート制限が存在する。

セカンダリレート制限の主な内容を以下に示す。

• 同時接続数

  最大100接続まで

• REST API

  1分あたり900ポイントまで

• GraphQL API

  1分あたり2,000ポイントまで

• コンテンツ作成 (Issueの作成等)

  1時間あたり制限あり

セカンダリレート制限に達した場合、レスポンスに retry-after ヘッダが含まれる。
このヘッダの値 (秒数) だけ待機してから再試行する必要がある。

継続して制限に達する場合は指数バックオフを使用する。

確認方法

現在のレート制限の状態は、レスポンスヘッダまたは専用のエンドポイントで確認できる。

下表に、レスポンスヘッダで確認できる情報を示す。

レート制限関連レスポンスヘッダ

ヘッダ名	説明
x-ratelimit-limit	時間あたりの最大リクエスト数
x-ratelimit-remaining	現在の期間内の残りリクエスト数
x-ratelimit-reset	レート制限がリセットされるUNIXタイムスタンプ
x-ratelimit-used	現在の期間内に使用したリクエスト数
retry-after	セカンダリレート制限に達した場合の待機秒数

専用エンドポイントでレート制限を確認することもできる。
このエンドポイントへのリクエスト自体はレート制限のカウントに含まれない。

curl -L \
     -H "Authorization: Bearer <YOUR_TOKEN>" \
     https://api.github.com/rate_limit

レスポンスの例を以下に示す。

 {
    "resources": {
       "core": {
          "limit": 5000,
          "remaining": 4999,
          "reset": 1700000000,
          "used": 1
       },
       "graphql": {
          "limit": 5000,
          "remaining": 4999,
          "reset": 1700000000,
          "used": 1
       },
       "search": {
          "limit": 30,
          "remaining": 29,
          "reset": 1700000000,
          "used": 1
       }
    },
    "rate": {
       "limit": 5000,
       "remaining": 4999,
       "reset": 1700000000,
       "used": 1
    }
 }

参考リンク

• GitHub REST API公式ドキュメント
• GitHub GraphQL API公式ドキュメント
• GitHub Apps公式ドキュメント
• GitHub Webhooks公式ドキュメント
• GitHub CLI公式マニュアル
• GitHub Octokit公式リポジトリ