验证为 GitHub 应用程序安装

关于以 GitHub App 安装形式进行身份验证

一旦您的 GitHub App 安装到某个账户上，您就可以使其以应用安装的身份进行身份验证，以发起 API 请求。这允许应用访问该安装拥有的资源，前提是已授予该应用必要的存储库访问权限和相应权限。应用安装发出的 API 请求归属于该应用。有关安装GitHub应用的详细信息，请参阅安装自己的GitHub应用。

例如，如果你要让应用更改组织拥有的“octo-org”项目上问题的 Status 字段，需要以应用的 octo-org 安装形式进行身份验证。问题的时间线将指出应用已更新状态。

若要以安装方式发出 API 请求，必须首先生成安装访问令牌。然后，你将在后续 API 请求的 Authorization 标头中发送安装访问令牌。还可以使用 GitHub's 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 令牌 (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页的详细信息，请参阅修改GitHub应用注册。
将 REST API POST 请求发送到 /app/installations/INSTALLATION_ID/access_tokens。将 JSON Web 令牌包含在请求的 Authorization 标头中。将 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: 2026-03-10"
```
（可选）可以使用 repositories 或 repository_ids 正文参数来指定安装访问令牌可以访问的各个存储库。如果不使用 repositories 或 repository_ids 来授予对特定存储库的访问权限，则安装访问令牌将有权访问已授权安装进行访问的所有存储库。不能授予安装访问令牌对安装未授权访问的存储库的权限。最多可以列出 500 个存储库。

（可选）使用 permissions 正文参数指定安装访问令牌应具有的权限。如果未指定 permissions，安装访问令牌将具有向应用授予的所有权限。不能向安装访问令牌授予未向应用授予的权限。

响应将包括安装访问令牌、令牌过期时间、令牌拥有的权限以及令牌可以访问的存储库（如果适用）。安装访问令牌将在 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 "http(s)://HOSTNAME/api/v3/meta" \
--header "Accept: application/vnd.github+json" \
--header "Authorization: Bearer INSTALLATION_ACCESS_TOKEN" \
--header "X-GitHub-Api-Version: 2026-03-10"

使用 Octokit.js SDK 以应用安装形式进行身份验证

可以使用 GitHub's Octokit.js SDK 作为应用安装进行身份验证。使用 SDK 进行身份验证的一个优点是，无需自行生成 JSON Web 令牌 (JWT)。此外，SDK 将负责为你重新生成安装访问令牌，你无需担心在一小时后过期。

注意

必须安装和导入 octokit，才能使用 Octokit.js 库。以下示例根据 ES6 使用导入语句。有关不同安装和导入方法的详细信息，请参阅 Octokit.js 自述文件的用法部分。

使用 Octokit.js 通过安装 ID 进行身份验证

获取你的 GitHub AppID。您可以在您的 GitHub App 的设置页面上找到应用 ID。有关导航到设置 GitHub App页的详细信息，请参阅修改GitHub应用注册。
生成私钥。有关详细信息，请参阅“管理GitHub应用的私钥”。
获取要作为其身份进行身份验证的安装 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 终结点”。

从 App 导入 octokit。创建 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")
```

使用 Octokit.js 进行身份验证以响应 Webhook 事件

Octokit.js SDK 还会将经过预身份验证的 octokit 实例传递给 Webhook 事件处理程序。

获取你的 GitHub App 的 ID。你可以在你的 GitHub App 的设置页面上找到应用 ID。有关导航到设置 GitHub App页的详细信息，请参阅修改GitHub应用注册。
生成私钥。有关详细信息，请参阅“管理GitHub应用的私钥”。
获取在应用的设置中指定的 Webhook 密钥。有关 Webhook 密钥的详细信息，请参阅将 Webhook 与 GitHub 应用配合使用。

从 App 导入 octokit。创建 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 自述文件的 Webhook 部分。例如，要在提交问题后为问题创建注释，请参考以下内容：

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": "2026-03-10",
      },
    }
  )
});

在本文中