GitHub App インストールとしての認証について
GitHub App がアカウントにインストールされたら、API 要求に対してアプリ インストールとして認証を行うことができます。 これにより、アプリはそのインストールによって所有されているリソースにアクセスできます (アプリに必要なリポジトリ アクセス権とアクセス許可が付与されている限り)。 アプリ インストールによって行われた API 要求は、アプリに帰属します。 GitHub App のインストールについて詳しくは、「GitHub App のインストール」を参照してください。
たとえば、"octo-org" という Organization が所有するプロジェクトに対するイシューの Status
フィールドをアプリで変更する場合は、アプリの octo-org インストールとして認証します。 イシューのタイムラインには、アプリによって状態が更新されたことが示されます。
インストールとして API 要求を行うには、まずインストール アクセス トークンを生成する必要があります。 次に、後続の API 要求の Authorization
ヘッダーで、インストール アクセス トークンを送信します。 GitHub の Octokit SDK を使うこともできます。これを使ってインストール アクセス トークンを生成できます。
一部の REST API エンドポイントはインストール アクセス トークンを受け入れず、ほとんどの REST API エンドポイントでは、エンドポイントを使用するために、アプリには特定のアクセス許可が必要です。 REST API エンドポイントがインストール アクセス トークンを受け入れるかどうかを確認し、必要なアクセス許可を確認するには、エンドポイントのドキュメントを参照してください。
アプリ インストールでは、GraphQL API を使用することもできます。 REST API と同様に、アプリには GraphQL API のオブジェクトにアクセスするための特定のアクセス許可が必要です。 GraphQL 要求の場合は、作成する GraphQL クエリとミューテーションに必要なアクセス許可がアプリにあることをテストする必要があります。
インストール アクセス トークンを使って、HTTP ベースの Git アクセスの認証を行うこともできます。 アプリには、"コンテンツ" リポジトリのアクセス許可が必要です。 その後は、インストール アクセス トークンを HTTP パスワードとして使用できます。 TOKEN
をインストール アクセス トークンに置き換えます: git clone https://x-access-token:TOKEN@github.com/owner/repo.git
。
インストール アクセス トークンを使用して行われた要求は、"サーバー間" 要求と呼ばれることもあります。
アプリ インストールとしてではなく、ユーザーに代わるアプリとして認証する方法について詳しくは、「ユーザーに代わって GitHub アプリで認証する」を参照してください。
インストール アクセス トークンを使ってアプリ インストールとして認証する
インストール アクセス トークンを使ってインストールとして認証するには、まず REST API を使ってインストール アクセス トークンを生成します。 次に、REST API または GraphQL API 要求の Authorization
ヘッダーでそのインストール アクセス トークンを使用します。 インストール アクセス トークンは 1 時間後に期限切れになります。
インストール アクセス トークンの生成
-
アプリの JSON Web Token (JWT) を生成します。 詳細については、「GitHub アプリの JSON Web トークン (JWT) の生成」を参照してください。
-
認証に使いたいインストールの ID を取得します。
Webhook イベントに応答する場合、Webhook ペイロードにはインストール ID が含まれます。
REST API を使って、アプリのインストールの ID を見つけることもできます。 たとえば、
GET /users/{username}/installation
、GET /repos/{owner}/{repo}/installation
、GET /orgs/{org}/installation
、またはGET /app/installations
エンドポイントでインストール ID を取得できます。 詳しくは、「GitHub Apps用 REST API エンドポイント」をご覧ください。アプリ ID は、アプリの設定ページでも確認できます。 アプリ ID は、クライアント ID とは異なります。 GitHub App の設定ページに移動する方法の詳細については、「AUTOTITLE」を参照してください。
-
REST API
POST
要求を/app/installations/INSTALLATION_ID/access_tokens
に送信します。 要求のAuthorization
ヘッダーに JSON Web トークンを含めます。INSTALLATION_ID
を、認証に使いたいインストールの ID に置き換えます。たとえば、次の curl 要求を送信します。
INSTALLATION_ID
をインストールの ID に、JWT
を JSON Web トークンに置き換えてください。curl --request POST \ --url "https://api.github.com/app/installations/INSTALLATION_ID/access_tokens" \ --header "Accept: application/vnd.github+json" \ --header "Authorization: Bearer JWT" \ --header "X-GitHub-Api-Version: 2022-11-28"
必要に応じて、
repositories
またはrepository_ids
本文パラメーターを使って、インストール アクセス トークンがアクセスできる個々のリポジトリを指定できます。repositories
またはrepository_ids
を使って特定のリポジトリへのアクセス権を付与しない場合、インストール アクセス トークンでは、インストールがアクセス権を付与されたすべてのリポジトリにアクセスできます。 インストール アクセス トークンには、インストールがアクセス権を付与されていないリポジトリへのアクセス権を付与できません。最大 500 個のリポジトリを一覧表示できます。必要に応じて、
permissions
本文パラメーターを使って、インストール アクセス トークンに必要なアクセス許可を指定します。permissions
が指定されていない場合、インストール アクセス トークンには、アプリに付与されたすべてのアクセス許可が付与されます。 インストール アクセス トークンに、アプリが付与されていないアクセス許可を付与することはできません。permissions
パラメーターを使用してトークンのアクセスを減らす場合、要求内のアクセス許可の数と、トークンがアクセスできるリポジトリの数が原因で、トークンの複雑さが増加します。 複雑さが大きすぎる場合は、サポートできるリポジトリの最大数を示すエラー メッセージが表示されます。 この場合は、permissions
パラメーターを使用して要求するアクセス許可を減らすか、repositories
またはrepository_ids
パラメーターを使用して要求するリポジトリの数を減らすか、Organization 内のall
リポジトリにアプリをインストールする必要があります。応答には、インストール アクセス トークン、トークンの有効期限が切れる時刻、トークンが持つアクセス許可、トークンがアクセスできるリポジトリが含まれます。 インストール アクセス トークンは 1 時間後に期限切れになります。
このエンドポイントについて詳しくは、「GitHub Apps用 REST API エンドポイント」をご覧ください。
注: ほとんどの場合は、
Authorization: Bearer
またはAuthorization: token
を使用してトークンを渡すことができます。 ただし、JSON Web トークン (JWT) を渡す場合は、Authorization: Bearer
を使用する必要があります。
インストール アクセス トークンを使った認証
インストール アクセス トークンを使って認証を行うには、それを API 要求の Authorization
ヘッダーに含めます。 アクセス トークンは、GraphQL API と REST API の両方で動作します。
アプリにはエンドポイントを使用するために必要なアクセス許可が必要です。 詳しくは、「GitHub アプリのアクセス許可を選択する」を参照してください。
次の例では、INSTALLATION_ACCESS_TOKEN
をインストール アクセス トークンに置き換えてください。
curl --request GET \
--url "https://api.github.com/meta" \
--header "Accept: application/vnd.github+json" \
--header "Authorization: Bearer INSTALLATION_ACCESS_TOKEN" \
--header "X-GitHub-Api-Version: 2022-11-28"
Octokit.js SDK を使ってアプリ インストールとして認証する
GitHub の Octokit.js SDK を使って、アプリ インストールとして認証できます。 SDK を使って認証を行う利点の 1 つは、JSON Web Token (JWT) を自分で生成する必要がないことです。 さらに、SDK によってインストール アクセス トークンの再生成が管理されるため、1 時間の有効期限について心配する必要がありません。
Octokit.js ライブラリを使うには、octokit
をインストールしてインポートする必要があります。 次の例では、ES6 に従って import ステートメントを使っています。 さまざまなインストールとインポートの方法について詳しくは、Octokit.js の README の「使用法」セクションを参照してください。
Octokit.js を使ってインストール ID で認証する
-
GitHub App の ID を取得します。 アプリの ID は、GitHub App の設定ページで確認できます。 GitHub App の設定ページに移動する方法の詳細については、「AUTOTITLE」を参照してください。
-
秘密キーを作成します。 詳細については、「GitHub Apps の秘密キーの管理」を参照してください。
-
認証に使いたいインストールの ID を取得します。
Webhook イベントに応答する場合、Webhook ペイロードにはインストール ID が含まれます。
REST API を使って、アプリのインストールの ID を見つけることもできます。 たとえば、
GET /users/{username}/installation
、GET /repos/{owner}/{repo}/installation
、GET /orgs/{org}/installation
、またはGET /app/installations
エンドポイントでインストール ID を取得できます。 詳細については、「GitHub Apps用 REST API エンドポイント」を参照してください。 -
octokit
からApp
をインポートします。App
の新しいインスタンスを作成します。 次の例では、APP_ID
をアプリの ID への参照に置き換えます。PRIVATE_KEY
をアプリの秘密キーへの参照に置き換えます。JavaScript import { App } from "octokit"; const app = new App({ appId: APP_ID, privateKey: PRIVATE_KEY, });
import { App } from "octokit"; const app = new App({ appId: APP_ID, privateKey: PRIVATE_KEY, });
-
getInstallationOctokit
メソッドを使って、認証されたoctokit
インスタンスを作成します。 次の例では、INSTALLATION_ID
を、代わりに認証するアプリのインストールの ID に置き換えます。JavaScript const octokit = await app.getInstallationOctokit(INSTALLATION_ID);
const octokit = await app.getInstallationOctokit(INSTALLATION_ID);
-
octokit
メソッドを使って、API に対して要求を行います。アプリにはエンドポイントを使用するために必要なアクセス許可が必要です。 詳しくは、「GitHub アプリのアクセス許可を選択する」を参照してください。
たとえば、GraphQL API に対して要求を行う場合:
JavaScript await octokit.graphql(` query { viewer { login } } `)
await octokit.graphql(` query { viewer { login } } `)
たとえば、REST API に対して要求を行う場合:
JavaScript await octokit.request("GET /meta")
await octokit.request("GET /meta")
Webhook イベントに応答して Octokit.js を使って認証する
Octokit.js SDK では、事前に認証された octokit
インスタンスも Webhook イベント ハンドラーに渡されます。
-
GitHub App の ID を取得します。 アプリの ID は、GitHub App の設定ページで確認できます。 GitHub App の設定ページに移動する方法の詳細については、「AUTOTITLE」を参照してください。
-
秘密キーを作成します。 詳細については、「GitHub Apps の秘密キーの管理」を参照してください。
-
アプリの設定で指定した Webhook シークレットを取得します。 Webhook シークレットについて詳しくは、「GitHub Apps での Webhook の使用」をご覧ください。
-
octokit
からApp
をインポートします。App
の新しいインスタンスを作成します。 次の例では、APP_ID
をアプリの ID への参照に置き換えます。PRIVATE_KEY
をアプリの秘密キーへの参照に置き換えます。WEBHOOK_SECRET
をアプリの Webhook シークレットに置き換えます。JavaScript import { App } from "octokit"; const app = new App({ appId: APP_ID, privateKey: PRIVATE_KEY, webhooks: { WEBHOOK_SECRET }, });
import { App } from "octokit"; const app = new App({ appId: APP_ID, privateKey: PRIVATE_KEY, webhooks: { WEBHOOK_SECRET }, });
-
app.webhooks.*
メソッドを使って Webhook イベントを処理します。 詳しくは、Octokit.js の README の Webhooks セクションを参照してください。 たとえば、イシューが開かれたときにイシューに対してコメントを作成するには、次のようにします。app.webhooks.on("issues.opened", ({ octokit, payload }) => { await octokit.request("POST /repos/{owner}/{repo}/issues/{issue_number}/comments", { owner: payload.repository.owner.login, repo: payload.repository.name, issue_number: payload.issue.number, body: `This is a bot post in response to this issue being opened.`, headers: { "x-github-api-version": "2022-11-28", }, } ) });