GitHub - APIのソースを表示

== 概要 ==
GitHub APIは、GitHubのデータやサービスにプログラムからアクセスするためのインターフェースである。<br>
<br>
GitHub APIには2種類のAPIが提供されている。<br>
<br>
<center>
{| class="wikitable"
|+ GitHub APIの種類
|-
! 種類 !! 説明
|-
| REST API || ベースURL: https://api.github.com/<br>HTTPメソッド (GET、POST、PATCH、PUT、DELETE) を使用してリソースを操作する。<br>シンプルなリクエスト・レスポンスモデルで、幅広い用途に対応する。
|-
| GraphQL API || エンドポイント: https://api.github.com/graphql<br>必要なデータのみを指定して取得できる柔軟なクエリ言語を使用する。<br>複数リソースのデータを1回のリクエストで取得できるため、オーバーフェッチを防止できる。
|}
</center>
<br>
両APIとも認証が必要な操作と不要な操作があるが、認証を行うことでレート制限が緩和され、プライベートリポジトリにもアクセス可能になる。<br>
<br><br>

== 認証 ==
GitHub APIの認証方式は複数存在する。<br>
用途に応じて適切な認証方式を選択する。<br>
<br>
==== Personal Access Token ====
Personal Access Token (PAT) は、個人のGitHubアカウントの代わりにAPIリクエストを認証するためのトークンである。<br>
<br>
PATには2種類ある。<br>
<br>
===== Fine-grained Personal Access Token (推奨) =====
Fine-grained PATは、より細かい権限制御が可能な新しい形式のトークンである。<br>
<br>
* 特定のリポジトリに対してのみアクセス権を付与できる。
* 各操作 (エンドポイント) 単位で権限を設定できる。
* 有効期限の設定が必須である。
* GitHub.comの[Settings] - [Developer settings] - [Personal access tokens] - [Fine-grained tokens]から作成する。
<br>
===== Classic Personal Access Token =====
Classic PATは、従来のスコープベースのトークンである。<br>
<br>
* <code>repo</code>、<code>user</code>、<code>admin:org</code> 等のスコープ単位で権限を付与する。
* 全リポジトリへのアクセスが許可されるため、Fine-grained PATより権限が広くなりやすい。
* GitHub.comの[Settings] - [Developer settings] - [Personal access tokens] - [Tokens (classic)]から作成する。
<br>
PATを使用する時は、リクエストヘッダに以下に示す形式で指定する。<br>
<br>
 Authorization: Bearer <YOUR_TOKEN>
 または
 Authorization: token <YOUR_TOKEN>
<br>
==== GitHub Apps ====
GitHub Appsは、GitHubプラットフォーム上に構築するアプリケーションのための認証方式である。<br>
<br>
GitHub Appsは2段階の認証方式を使用する。<br>
<br>
* JWT認証 (アプリ自身の認証)
*: アプリのプライベートキーを使用してJWT (JSON Web Token) を生成する。
*: JWTは10分間有効である。
*: インストールアクセストークンの取得に使用する。
* インストールアクセストークン
*: JWTを使用して <code>POST /app/installations/{installation_id}/access_tokens</code> に対してリクエストを送信することで取得する。
*: 短期間 (1時間) で自動失効する。
*: 実際のAPIリクエストにはインストールアクセストークンを使用する。
<br>
==== OAuth Apps ====
OAuth Appsは、ユーザの代わりにGitHub APIにアクセスするための認証方式である。<br>
<br>
* OAuthフローを通じてユーザの認可を得る。
* ユーザアクセストークンを取得してAPIリクエストに使用する。
* GitHub AppsのOAuth機能と比較して、権限管理の粒度が粗い。
* 新規の用途には、GitHub Appsの使用が推奨される。
<br>
==== GITHUB_TOKEN ====
<code>GITHUB_TOKEN</code> は、GitHub Actionsワークフロー内で自動的に生成されるシークレットトークンである。<br>
<br>
* ワークフロー実行ごとに自動生成される。
* ワークフローが完了すると自動的に失効する。
* リポジトリのActionsの設定でデフォルトの権限を調整できる。
* 外部リソースへのアクセスには別途認証が必要である。
<br>
GitHub Actionsのワークフロー内では以下に示すように使用する。<br>
<br>
 <syntaxhighlight lang="yaml">
 - name: GitHub APIを呼び出す
   run: |
      curl -H "Authorization: Bearer ${{ secrets.GITHUB_TOKEN }}" \
           https://api.github.com/repos/${{ github.repository }}
 </syntaxhighlight>
<br>
==== 認証方法の比較 ====
下表に、各認証方式の特徴を示す。<br>
<br>
<center>
{| class="wikitable"
|+ 認証方式の比較
! 認証方式 !! 用途 !! 権限の粒度 !! 有効期限
|-
| Fine-grained PAT || 個人の開発、スクリプト || リポジトリ単位・操作単位 || 設定必須 (最大1年)
|-
| Classic PAT || 個人の開発、スクリプト || スコープ単位 || 設定可能 (無期限も可)
|-
| GitHub Apps || サードパーティアプリ、CI/CD || リポジトリ単位・権限単位 || インストールトークンは1時間
|-
| OAuth Apps || ユーザ認可が必要なアプリ || スコープ単位 || 設定による
|-
| GITHUB_TOKEN || GitHub Actionsワークフロー || リポジトリ権限に準拠 || ワークフロー終了まで
|}
</center>
<br><br>

== REST API ==
==== エンドポイントの構造 ====
GitHub REST APIのベースURLは https://api.github.com/ である。<br>
<br>
エンドポイントは以下の形式で構成される。<br>
<br>
 https://api.github.com/{リソースパス}
<br>
下表に、リソースパスの例を示す。<br>
<br>
<center>
{| class="wikitable"
|+ REST APIの主要なエンドポイント例
|-
! エンドポイント !! 説明
|-
| <code>/repos/{owner}/{repo}</code> || 特定リポジトリの情報
|-
| <code>/repos/{owner}/{repo}/issues</code> || リポジトリのIssue一覧
|-
| <code>/user</code> || 認証済みユーザの情報
|-
| <code>/orgs/{org}</code> || 組織の情報
|}
</center>
<br>
下表に、HTTPメソッドと操作の対応を示す。<br>
<br>
<center>
{| class="wikitable"
! HTTPメソッド !! 操作内容
|-
| GET || リソースの取得
|-
| POST || リソースの作成
|-
| PATCH || リソースの部分更新
|-
| PUT || リソースの置換・関連付け
|-
| DELETE || リソースの削除
|}
</center>
<br>
==== リクエストとレスポンス ====
GitHub REST APIのリクエストには、以下に示すヘッダを設定することが推奨される。<br>
<br>
<center>
{| class="wikitable"
|+ 主要なリクエストヘッダ
! ヘッダ名 !! 説明 !! 例
|-
| <code>Authorization</code> || 認証トークン || <u>Bearer ghp_xxxxxxxxxxxx</u>
|-
| <code>Accept</code> || レスポンス形式の指定 || <u>application/vnd.github+json</u>
|-
| <code>X-GitHub-Api-Version</code> || APIバージョンの指定 || <u>2022-11-28</u>
|-
| <code>User-Agent</code> || アプリケーション識別子 || <u>MyApp/1.0</u>
|}
</center>
<br>
レスポンスは、JSON形式で返される。<br>
日時は、ISO 8601形式 (例: <u>2024-01-15T12:00:00Z</u>) で表現される。<br>
<br>
==== ページネーション ====
複数件のリソースを返すエンドポイントでは、ページネーションが使用される。<br>
<br>
* <code>per_page</code> クエリパラメータでページあたりの件数を指定する。(最大100)
* <code>page</code> クエリパラメータでページ番号を指定する。
* レスポンスの <code>Link</code> ヘッダに次ページ、前ページ等のURLが含まれる。
<br>
<code>Link</code> ヘッダの例を以下に示す。<br>
<br>
 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"
<br>
<code>rel</code> の値は <u>next</u>、<u>prev</u>、<u>first</u>、<u>last</u> の4種類がある。<br>
<br>
==== 主要なエンドポイント ====
下表に、よく使用される主要なエンドポイントを示す。<br>
<br>
<center>
{| class="wikitable"
|+ 主要エンドポイント一覧
! カテゴリ !! メソッド !! エンドポイント !! 説明
|-
| リポジトリ || GET || <code>/repos/{owner}/{repo}</code> || リポジトリ情報の取得
|-
| リポジトリ || POST || <code>/user/repos</code> || リポジトリの作成
|-
| リポジトリ || GET || <code>/repos/{owner}/{repo}/contents/{path}</code> || ファイル内容の取得
|-
| Issues || GET || <code>/repos/{owner}/{repo}/issues</code> || Issue一覧の取得
|-
| Issues || POST || <code>/repos/{owner}/{repo}/issues</code> || Issueの作成
|-
| Issues || PATCH || <code>/repos/{owner}/{repo}/issues/{issue_number}</code> || Issueの更新
|-
| Pull Requests || GET || <code>/repos/{owner}/{repo}/pulls</code> || PR一覧の取得
|-
| Pull Requests || POST || <code>/repos/{owner}/{repo}/pulls</code> || PRの作成
|-
| Pull Requests || PUT || <code>/repos/{owner}/{repo}/pulls/{pull_number}/merge</code> || PRのマージ
|-
| ユーザ || GET || <code>/user</code> || 認証済みユーザ情報の取得
|-
| ユーザ || GET || <code>/users/{username}</code> || 特定ユーザ情報の取得
|}
</center>
<br>
==== 使用例 ====
curlを使用したREST APIのリクエスト例を以下に示す。<br>
<br>
* リポジトリ情報の取得
*: <syntaxhighlight lang="text">
 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
 </syntaxhighlight>
*: <br>
* Issueの作成
*: <syntaxhighlight lang="text">
 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"]}'
 </syntaxhighlight>
*: <br>
* Issue一覧の取得 (ページネーション使用)
*: <syntaxhighlight lang="text">
 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"
 </syntaxhighlight>
<br><br>

== GraphQL API ==
==== GraphQLとは ====
GraphQLは、APIのためのクエリ言語であり、必要なデータのみを指定して取得できる仕組みである。<br>
<br>
REST APIと比較した時のGraphQL APIのメリットを以下に示す。<br>
<br>
<center>
{| class="wikitable"
|+ REST APIと比較したGraphQL APIのメリット
|-
! 観点 !! メリット
|-
| データ取得の効率性 || 必要なフィールドのみを指定して取得するため、不要なデータの転送を削減できる。
|-
| リクエスト回数の削減 || 複数のリソースに関するデータを1回のリクエストで取得できる。
|-
| APIの明確性 || 型システムによりAPIの構造が明確である。
|-
| クライアントの柔軟性 || クライアント側でデータ要件を柔軟に調整できる。
|}
</center>
<br>
==== エンドポイント ====
GitHub GraphQL APIのエンドポイントは以下の1つのみである。<br>
<br>
 https://api.github.com/graphql
<br>
REST APIとは異なり、全てのリクエストは <code>POST</code> メソッドで送信する。<br>
リクエストボディにJSONとしてクエリを含める。<br>
<br>
 curl -L \
      -X POST \
      -H "Authorization: Bearer <YOUR_TOKEN>" \
      -H "Content-Type: application/json" \
      https://api.github.com/graphql \
      -d '{"query": "{ viewer { login } }"}'
<br>
==== クエリの基本 ====
GraphQLのクエリは、取得したいデータの構造を宣言的に記述する。<br>
<br>
* 認証済みユーザの情報を取得するクエリの例
*: <syntaxhighlight lang="json">
 {
    "query": "query { viewer { login name email } }"
 }
 </syntaxhighlight>
*: <br>
* 特定リポジトリの情報を取得するクエリの例
*: <syntaxhighlight lang="json">
 {
    "query": "query { repository(owner: \"octocat\", name: \"hello-world\") { name description stargazerCount forkCount } }"
 }
 </syntaxhighlight>
*: <br>
* 横断検索 (search) を使用したクエリの例
*: searchは最大1,000件の結果を返す。
*: <syntaxhighlight lang="json">
 {
    "query": "query { search(query: \"repo:octocat/hello-world is:issue is:open\", type: ISSUE, first: 10) { issueCount nodes { ... on Issue { title number } } } }"
 }
 </syntaxhighlight>
<br>
==== ミューテーション ====
GraphQLでデータを変更する操作には、ミューテーション (mutation) を使用する。<br>
<br>
Issueにリアクションを追加するミューテーションの例を以下に示す。<br>
<br>
 <syntaxhighlight lang="json">
 {
    "query": "mutation { addReaction(input: {subjectId: \"MDU6SXNzdWUx\", content: THUMBS_UP}) { reaction { content } subject { id } } }"
 }
 </syntaxhighlight>
<br>
==== 変数の使用 ====
GraphQLでは、クエリと変数を分離して記述できる。<br>
変数を使用することにより、クエリの再利用性が向上して、特殊文字のエスケープが不要になる。<br>
<br>
 <syntaxhighlight lang="json">
 {
    "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"
    }
 }
 </syntaxhighlight>
<br><br>

== GitHub CLI (gh) ==
==== インストールと認証 ====
GitHub CLI (gh) は、コマンドラインからGitHubの操作を行うための公式ツールである。<br>
<br>
インストール方法を以下に示す。<br>
<br>
 # MacOS (Homebrew)
 brew install gh
 
 # RHEL
 sudo dnf install gh
 
 # SUSE
 sudo zypper install gh
 
 # Debian / Ubuntu
 sudo apt install gh
<br>
インストール後、認証を行う。<br>
<br>
 # 対話的な認証フロー
 gh auth login
 
 # 認証状態の確認
 gh auth status
 
 # 環境変数を使用した認証 (CI/CD環境等)
 export GH_TOKEN=<YOUR_TOKEN>
<br>
==== 主要コマンド ====
下表に、GitHub CLIで使用できる主要なコマンドを示す。<br>
<br>
<center>
{| class="wikitable"
|+ GitHub CLI 主要コマンド一覧
! コマンド !! 主なサブコマンド !! 説明
|-
| <code>gh repo</code> || <code>create</code><br><code>clone</code><br><code>fork</code><br><code>view</code><br><code>list</code> || リポジトリの管理
|-
| <code>gh issue</code> || <code>create</code><br><code>list</code><br><code>view</code><br><code>close</code><br><code>edit</code> || Issueの管理
|-
| <code>gh pr</code> || <code>create</code><br><code>list</code><br><code>view</code><br><code>merge</code><br><code>checkout</code><br><code>review</code> || Pull Requestの管理
|-
| <code>gh release</code> || <code>create</code><br><code>list</code><br><code>download</code><br><code>view</code> || リリースの管理
|-
| <code>gh workflow</code> || <code>run</code><br><code>list</code><br><code>view</code><br><code>enable</code><br><code>disable</code> || GitHub Actionsワークフローの管理
|-
| <code>gh api</code> || - || REST / GraphQL APIの直接呼び出し
|-
| <code>gh alias</code> || <code>set</code><br><code>list</code><br><code>delete</code> || コマンドエイリアスの管理
|}
</center>
<br>
使用例を以下に示す。<br>
<br>
 # リポジトリのクローン
 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
<br>
==== gh api ====
<code>gh api</code> コマンドを使用することにより、REST API および GraphQL APIを直接呼び出すことができる。<br>
<br>
 # 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
<br>
==== エイリアス ====
よく使用するコマンドにエイリアスを設定することができる。<br>
<br>
 # エイリアスの設定
 gh alias set prl 'pr list --state open'
 
 # エイリアスの一覧表示
 gh alias list
 
 # エイリアスの削除
 gh alias delete prl
<br><br>

== Octokit ==
Octokitは、GitHub APIの公式クライアントライブラリである。<br>
<br>
各言語向けに提供されており、APIの呼び出しを簡略化できる。<br>
<br>
==== Octokit.js ====
Octokit.jsは、JavaScript / TypeScript向けのGitHub APIクライアントライブラリである。<br>
Webブラウザ、Node.js、Denoの各環境で動作する。<br>
<br>
インストール方法を以下に示す。<br>
<br>
 npm install @octokit/rest
 # または
 npm install octokit
<br>
基本的な使用例を以下に示す。<br>
<br>
 <syntaxhighlight lang="javascript">
 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);
 </syntaxhighlight>
<br>
ページネーションを自動処理する <code>paginate()</code> メソッドの使用例を以下に示す。<br>
<br>
 <syntaxhighlight lang="javascript">
 // 全Issue一覧の取得 (自動ページネーション)
 const issues = await octokit.paginate(octokit.rest.issues.listForRepo, {
    owner: "octocat",
    repo: "hello-world",
    state: "open",
    per_page: 100,
 });
 
 console.log(`取得件数: ${issues.length}`);
 </syntaxhighlight>
<br>
==== Octokit.rb ====
Octokit.rbは、Ruby向けのGitHub APIクライアントライブラリである。<br>
<br>
インストール方法を以下に示す。<br>
<br>
 gem install octokit
<br>
基本的な使用例を以下に示す。<br>
<br>
 <syntaxhighlight lang="ruby">
 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
 </syntaxhighlight>
<br><br>

== Webhook ==
==== Webhookとは ====
WebhookはGitHub上でイベントが発生した時に、指定したURLに対してHTTP POSTリクエストを自動的に送信する仕組みである。<br>
<br>
Webhookを使用することにより、リポジトリへのプッシュ、IssueやPull Requestの作成・更新、デプロイイベントの発生等、様々なGitHubイベントに反応した自動化を実現できる。<br>
<br>
==== Webhookの設定 ====
Webhookは、リポジトリ または Organizationの設定から作成できる。<br>
<br>
設定項目を以下に示す。<br>
<br>
<center>
{| class="wikitable"
|+ Webhookの設定項目
|-
! 項目 !! 説明
|-
| ペイロードURL || Webhookのイベント発生時にリクエストを受信するエンドポイントのURL<br>公開されたHTTPSのURLである必要がある。
|-
| コンテンツタイプ || <code>application/json</code> (推奨)<br>または<br><code>application/x-www-form-urlencoded</code><br>を選択する。
|-
| シークレット || Webhookのペイロードを検証するための秘密の文字列<br>設定することでHTTPリクエストの正当性を確認できる。
|-
| イベントの選択 || 通知を受けたいイベントを個別に選択、または、全イベントを受信するかを設定する。
|}
</center>
<br>
==== イベントの種類 ====
GitHubでは、70以上のWebhookイベントが提供されている。<br>
<br>
下表に、主要なイベントを示す。<br>
<br>
<center>
{| class="wikitable"
|+ 主要Webhookイベント
! イベント名 !! 説明
|-
| <code>push</code> || リポジトリへのコミットのプッシュ
|-
| <code>pull_request</code> || Pull Requestの作成、更新、クローズ等
|-
| <code>issues</code> || Issueの作成、更新、クローズ等
|-
| <code>create</code> || ブランチやタグの作成
|-
| <code>delete</code> || ブランチやタグの削除
|-
| <code>release</code> || リリースの公開・更新等
|-
| <code>workflow_run</code> || GitHub Actionsワークフローの実行
|-
| <code>code_scanning_alert</code> || コードスキャンアラートの検出
|-
| <code>secret_scanning_alert</code> || シークレットスキャンアラートの検出
|}
</center>
<br>
==== シークレットによる検証 ====
Webhookのシークレットを設定している場合、GitHubはリクエストに <code>X-Hub-Signature-256</code> ヘッダを付与する。<br>
このヘッダの値はHMAC-SHA256アルゴリズムを使用して計算されたシグネチャである。<br>
<br>
受信側でシグネチャを検証することにより、リクエストが正当なGitHubからのものであることを確認できる。<br>
<br>
Node.jsでの検証例を以下に示す。<br>
<br>
 <syntaxhighlight lang="javascript">
 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");
 });
 </syntaxhighlight>
<br>
下表に、配信時に付与される主要なヘッダを示す。<br>
<br>
<center>
{| class="wikitable"
|+ Webhookリクエストの主要なHTTPヘッダ
|-
! ヘッダー !! 説明
|-
| <code>X-GitHub-Event</code> || イベントの種類 (例: <u>push</u>、<u>pull_request</u>)
|-
| <code>X-GitHub-Delivery</code> || 配信を識別するUUID
|-
| <code>X-Hub-Signature-256</code> || HMAC-SHA256によるシグネチャ (シークレット設定時のみ)
|}
</center>
<br>
==== ペイロードの制限 ====
Webhookのペイロードには最大25[MB]の制限がある。<br>
<br>
ペイロードがこの制限を超える場合、GitHubはWebhookを送信せずに、配信履歴に記録される。<br>
<br>
<u>大量のコミットを含むプッシュイベント等で発生する可能性があるため、注意が必要である。</u><br>
<br><br>

== GitHub Apps ==
==== GitHub Appsとは ====
<u>GitHub Appsは、GitHubプラットフォーム上に構築するアプリケーションの形式であり、OAuth Appsより推奨される認証方式である。</u><br>
<br>
GitHub Appsの主な特徴を以下に示す。<br>
<br>
* Fine-grained permissionsにより、必要な権限のみを要求できる。
* 特定のリポジトリにのみインストールすることが可能である。
* ユーザの代わりではなく、アプリケーション自身として動作できる。
* SAML SSOが有効なOrganizationでは自動的に認可される。
<br>
==== OAuth Appsとの違い ====
下表に、GitHub AppsとOAuth Appsの主な違いを示す。<br>
<br>
<center>
{| class="wikitable"
|+ GitHub Apps vs OAuth Apps
! 比較項目 !! GitHub Apps !! OAuth Apps
|-
| 推奨度 || 推奨 || 非推奨 (新規用途)
|-
| 権限の粒度 || リポジトリ / 操作単位 || スコープ単位
|-
| インストール単位 || Organization または ユーザ || ユーザ
|-
| リポジトリの限定 || 特定リポジトリのみ可能 || 全リポジトリ対象
|-
| 動作主体 || アプリ自身またはユーザ || ユーザのみ
|-
| レート制限 || インストールごとにスケーリング || ユーザごと
|-
| SAML SSO対応 || 自動認可 || ユーザによる認可が必要
|}
</center>
<br>
==== GitHub Appの作成 ====
GitHub Appを新規作成する手順を以下に示す。<br>
<br>
# GitHub.comにログインして、[Settings]を開く。
# 左側のサイドバーから[Developer settings]を選択する。
# [GitHub Apps]を選択して、[New GitHub App]ボタンを押下する。
# アプリ名、ホームページURL、Webhook URL等の必須情報を入力する。
# 必要な権限 (Permissions) を設定する。
# サブスクライブするイベントを選択する。
# プライベートキーを生成してダウンロードする。
<br>
==== 認証方式 ====
GitHub Appsでは3種類の認証方式が提供されている。<br>
<br>
===== JWT認証 (アプリ自身の認証) =====
アプリ自身を認証するためにJWT (JSON Web Token) を使用する。<br>
<br>
* アプリのIDとプライベートキーを使用してJWTを生成する。
* JWTの有効期限は最大10分である。
* インストールアクセストークンの取得等、アプリレベルの操作に使用する。
<br>
 <syntaxhighlight lang="javascript">
 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" });
 </syntaxhighlight>
<br>
===== インストールアクセストークン =====
特定のインストールのリソースにアクセスするための短期トークンである。<br>
<br>
* JWTを使用して <u>POST /app/installations/{installation_id}/access_tokens</u> に対してリクエストを送信することで取得する。
* 有効期限は1時間で、自動的に失効する。
* 特定のリポジトリやリソースへのアクセスに使用する。
<br>
===== ユーザアクセストークン =====
<u>ユーザがGitHub Appを認可した後に取得できるトークンであり、ユーザの代わりにAPIを呼び出す場合に使用する。</u><br>
<br><br>

== レート制限 ==
==== プライマリレート制限 ====
GitHub APIには、APIの悪用を防ぐためのレート制限が設けられている。<br>
<br>
下表に、プライマリレート制限の上限を示す。<br>
<br>
<center>
{| class="wikitable"
|+ プライマリレート制限
! 認証状態 !! 上限 !! 備考
|-
| 認証なし || 60リクエスト / 時間 || IPアドレスごとに適用
|-
| PAT認証済み || 5,000リクエスト / 時間 || ユーザごとに適用
|-
| GitHub Enterprise Cloud || 15,000リクエスト / 時間 || Organizationメンバー
|-
| GitHub Apps (インストール) || 最低5,000リクエスト / 時間 || リポジトリ数に応じてスケーリング
|-
| GITHUB_TOKEN (Actions) || 1,000リクエスト / 時間 || リポジトリごとに適用
|}
</center>
<br>
==== セカンダリレート制限 ====
プライマリレート制限に加えて、サーバへの過負荷を防ぐためのセカンダリレート制限が存在する。<br>
<br>
セカンダリレート制限の主な内容を以下に示す。<br>
<br>
* 同時接続数
*: 最大100接続まで
* REST API
*: 1分あたり900ポイントまで
* GraphQL API
*: 1分あたり2,000ポイントまで
* コンテンツ作成 (Issueの作成等)
*: 1時間あたり制限あり
<br>
セカンダリレート制限に達した場合、レスポンスに <code>retry-after</code> ヘッダが含まれる。<br>
このヘッダの値 (秒数) だけ待機してから再試行する必要がある。<br>
<br>
継続して制限に達する場合は指数バックオフを使用する。<br>
<br>
==== 確認方法 ====
現在のレート制限の状態は、レスポンスヘッダまたは専用のエンドポイントで確認できる。<br>
<br>
下表に、レスポンスヘッダで確認できる情報を示す。<br>
<br>
<center>
{| class="wikitable"
|+ レート制限関連レスポンスヘッダ
! ヘッダ名 !! 説明
|-
| <code>x-ratelimit-limit</code> || 時間あたりの最大リクエスト数
|-
| <code>x-ratelimit-remaining</code> || 現在の期間内の残りリクエスト数
|-
| <code>x-ratelimit-reset</code> || レート制限がリセットされるUNIXタイムスタンプ
|-
| <code>x-ratelimit-used</code> || 現在の期間内に使用したリクエスト数
|-
| <code>retry-after</code> || セカンダリレート制限に達した場合の待機秒数
|}
</center>
<br>
専用エンドポイントでレート制限を確認することもできる。<br>
このエンドポイントへのリクエスト自体はレート制限のカウントに含まれない。<br>
<br>
 curl -L \
      -H "Authorization: Bearer <YOUR_TOKEN>" \
      https://api.github.com/rate_limit
<br>
レスポンスの例を以下に示す。<br>
<br>
 <syntaxhighlight lang="json">
 {
    "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
    }
 }
 </syntaxhighlight>
<br><br>

== 参考リンク ==
* [https://docs.github.com/ja/rest GitHub REST API公式ドキュメント]
* [https://docs.github.com/ja/graphql GitHub GraphQL API公式ドキュメント]
* [https://docs.github.com/ja/apps GitHub Apps公式ドキュメント]
* [https://docs.github.com/ja/webhooks GitHub Webhooks公式ドキュメント]
* [https://cli.github.com/manual/ GitHub CLI公式マニュアル]
* [https://github.com/octokit GitHub Octokit公式リポジトリ]
<br><br>


{{#seo:
|title={{PAGENAME}} : Exploring Electronics and SUSE Linux | MochiuWiki
|keywords=MochiuWiki,Mochiu,Wiki,Mochiu Wiki,GitHub,API,REST API,GraphQL,GitHub Apps,OAuth,Webhook,Octokit,GitHub CLI,gh,Personal Access Token,PAT,Rate Limit,SUSE,Linux
|description={{PAGENAME}} - GitHub APIの使い方に関するリファレンスガイド | This page is {{PAGENAME}} in our wiki about electronic circuits and SUSE Linux
|image=/resources/assets/MochiuLogo_Single_Blue.png
}}

__FORCETOC__
[[カテゴリ:Git]]