为 GitHub 应用生成安装访问令牌

关于安装访问令牌

为了以应用安装身份进行身份验证，您必须生成一个安装访问令牌。有关以应用安装身份进行身份验证的更多信息，请参阅“以 GitHub 应用安装身份进行身份验证”。

您应该保护您的安装访问令牌。有关更多信息，请参阅“创建 GitHub App 的最佳实践”。

生成安装访问令牌

1. 为您的应用程序生成一个 JSON Web 令牌 (JWT)。有关更多信息，请参阅“为 GitHub App 生成 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 App 的 REST API 端点”。

   您也可以在应用程序的设置页面上找到应用程序 ID。应用程序 ID 与客户端 ID 不同。有关导航到 GitHub App 设置页面的更多信息，请参阅“修改 GitHub App 注册”。

3. 向 /app/installations/INSTALLATION_ID/access_tokens 发送 REST API POST 请求。在请求的 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 参数请求更少的存储库，或在您的组织中的 all 存储库上安装应用程序。

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

   有关此端点的更多信息，请参阅“GitHub Apps 的 REST API 端点”。

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