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

了解如何为 GitHub App 生成安装访问令牌。

本文内容

关于安装访问令牌

若要以应用安装形式进行身份验证，必须生成安装访问令牌。 有关以应用安装形式进行身份验证的详细信息，请参阅“以 GitHub 应用安装形式进行身份验证”。

注意：可以使用 GitHub 的 Octokit SDK 以应用形式进行身份验证，而不是生成安装访问令牌。 SDK 将负责为你生成安装访问令牌，并在令牌过期后重新生成该令牌。 有关以应用安装形式进行身份验证的详细信息，请参阅“以 GitHub 应用安装形式进行身份验证”。

应确保安装访问令牌的安全。 有关详细信息，请参阅“创建 GitHub 应用的最佳做法”。

生成安装访问令牌

  1. 为应用生成 JSON Web 令牌 (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 的设置页，请参阅“修改 GitHub 应用注册”。

  3. 将 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 终结点”。

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