Skip to main content

GitHub App インストールとしての認証

GitHub App をインストールとして認証して、アプリがインストールされているアカウントが所有するリソースに影響する API 要求を行うことができます。

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 時間後に期限切れになります。

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

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

  2. 認証に使いたいインストールの ID を取得します。

    Webhook イベントに応答する場合、Webhook ペイロードにはインストール ID が含まれます。

    REST API を使って、アプリのインストールの ID を見つけることもできます。 たとえば、GET /users/{username}/installationGET /repos/{owner}/{repo}/installationGET /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 "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 で認証する

  1. GitHub App の ID を取得します。 アプリの ID は、GitHub App の設定ページで確認できます。 GitHub App の設定ページに移動する方法の詳細については、「AUTOTITLE」を参照してください。

  2. 秘密キーを作成します。 詳細については、「GitHub Apps の秘密キーの管理」を参照してください。

  3. 認証に使いたいインストールの ID を取得します。

    Webhook イベントに応答する場合、Webhook ペイロードにはインストール ID が含まれます。

    REST API を使って、アプリのインストールの ID を見つけることもできます。 たとえば、GET /users/{username}/installationGET /repos/{owner}/{repo}/installationGET /orgs/{org}/installation、または GET /app/installations エンドポイントでインストール ID を取得できます。 詳細については、「GitHub Apps用 REST API エンドポイント」を参照してください。

  4. octokit から App をインポートします。 App の新しいインスタンスを作成します。 次の例では、APP_ID をアプリの ID への参照に置き換えます。 PRIVATE_KEY をアプリの秘密キーへの参照に置き換えます。

    JavaScript
    import { App } from "octokit";
    
    const app = new App({
      appId: APP_ID,
      privateKey: PRIVATE_KEY,
    });
    
  5. getInstallationOctokit メソッドを使って、認証された octokit インスタンスを作成します。 次の例では、INSTALLATION_ID を、代わりに認証するアプリのインストールの ID に置き換えます。

    JavaScript
    const octokit = await app.getInstallationOctokit(INSTALLATION_ID);
    
  6. octokit メソッドを使って、API に対して要求を行います。

    アプリにはエンドポイントを使用するために必要なアクセス許可が必要です。 詳しくは、「GitHub アプリのアクセス許可を選択する」を参照してください。

    たとえば、GraphQL API に対して要求を行う場合:

    JavaScript
    await octokit.graphql(`
      query {
        viewer {
          login
        }
      }
      `)
    

    たとえば、REST API に対して要求を行う場合:

    JavaScript
    await octokit.request("GET /meta")
    

Webhook イベントに応答して Octokit.js を使って認証する

Octokit.js SDK では、事前に認証された octokit インスタンスも Webhook イベント ハンドラーに渡されます。

  1. GitHub App の ID を取得します。 アプリの ID は、GitHub App の設定ページで確認できます。 GitHub App の設定ページに移動する方法の詳細については、「AUTOTITLE」を参照してください。

  2. 秘密キーを作成します。 詳細については、「GitHub Apps の秘密キーの管理」を参照してください。

  3. アプリの設定で指定した Webhook シークレットを取得します。 Webhook シークレットについて詳しくは、「GitHub Apps での Webhook の使用」をご覧ください。

  4. 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 },
    });
    
  5. 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",
          },
        }
      )
    });