GitHub アプリのインストール アクセス トークンの生成

GitHub App のインストール アクセス トークンを生成する方法について説明します。

この記事の内容

インストール アクセス トークンについて

アプリ インストールとして認証するには、インストール アクセス トークンを生成する必要があります。 アプリ インストールとしての認証について詳しくは、「GitHub App インストールとしての認証」を参照してください。

注: インストール アクセス トークンを作成する代わりに、GitHub の Octokit SDK を使い、アプリとして認証できます。 SDK によってインストール アクセス トークンの生成が管理され、期限が切れるとトークンは再生成されます。 アプリ インストールとしての認証について詳しくは、「GitHub App インストールとしての認証」を参照してください。

インストール アクセス トークンはセキュリティで保護する必要があります。 詳しくは、「GitHub App を作成するためのベスト プラクティス」を参照してください。

インストール アクセス トークンの生成

  1. アプリの JSON Web Token (JWT) を生成します。 詳細については、「GitHub アプリの JSON Web トークン (JWT) の生成」を参照してください。

  2. 認証に使いたいインストールの 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」を参照してください。

  3. 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 "http(s)://HOSTNAME/api/v3/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 を使用する必要があります。