验证为 GitHub 应用程序安装

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

在帐户上安装 GitHub App后，你可以将其以 API 请求的应用安装形式进行身份验证。这允许应用访问该安装拥有的资源，前提是已授予该应用必要的存储库访问权限和相应权限。应用安装发出的 API 请求归属于该应用。有关安装 GitHub 应用的详细信息，请参阅安装 GitHub 应用。

例如，如果你要让应用更改组织拥有的“octo-org”项目上问题的 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 令牌 (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: 2022-11-28"
```
（可选）可以使用 repositories 或 repository_ids 正文参数来指定安装访问令牌可以访问的各个存储库。如果不使用 repositories 或 repository_ids 来授予对特定存储库的访问权限，则安装访问令牌将有权访问已授权安装进行访问的所有存储库。无法向安装访问令牌授予对未授予安装访问权限的存储库的访问权限。最多可以列出 500 个存储库。

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

使用 permissions 参数降低令牌的访问权限时，由于请求中的权限数量以及令牌将有权访问的存储库数量，令牌的复杂性会增加。如果复杂性太大，将收到一条错误消息，指出可支持的最大存储库数量。在这种情况下，应使用 permissions 参数请求更少的权限、使用 repositories 或 repository_ids 参数请求更少的存储库，或在组织中的 all 存储库上安装应用。

响应将包括安装访问令牌、令牌过期时间、令牌拥有的权限以及令牌可以访问的存储库。安装访问令牌将在 1 小时后过期。

有关此终结点的详细信息，请参阅“GitHub Apps 的 REST API 终结点”。

Note

在大多数情况下，可以使用 Authorization: Bearer 或 Authorization: token 传递令牌。但是，如果要传递 JSON Web 令牌 (JWT)，则必须使用 Authorization: Bearer。

使用安装访问令牌进行身份验证

要使用安装访问令牌进行身份验证，请将它添加到 API 请求的 Authorization 标头中。访问令牌将同时适用于 GraphQL API 和 REST API。

应用必须具有使用终结点所需的权限。有关详细信息，请参阅“为 GitHub Apps 选择权限”。

在以下示例中，将 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: 2022-11-28"

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

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

Note

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

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

获取 GitHub App 的 ID。可以在 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 终结点”。

从 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 Apps 选择权限”。

例如，若要向 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 应用配合使用”。

从 octokit 导入 App。创建 App 的一个新实例。在以下示例中，将 APP_ID 替换为对应用 ID 的引用。将 PRIVATE_KEY 替换为对应用私钥的引用。将 WEBHOOK_SECRET 替换为应用的 Webhook 机密。