关于安装访问令牌
若要以应用安装形式进行身份验证,必须生成安装访问令牌。 有关以应用安装形式进行身份验证的详细信息,请参阅“以 GitHub 应用安装形式进行身份验证”。
注意:可以使用 GitHub 的 Octokit SDK 以应用形式进行身份验证,而不是生成安装访问令牌。 SDK 将负责为你生成安装访问令牌,并在令牌过期后重新生成该令牌。 有关以应用安装形式进行身份验证的详细信息,请参阅“以 GitHub 应用安装形式进行身份验证”。
应确保安装访问令牌的安全。 有关详细信息,请参阅“创建 GitHub 应用的最佳做法”。
生成安装访问令牌
-
为应用生成 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 终结点”。
注意:在大多数情况下,可以使用
Authorization: Bearer
或Authorization: token
传递令牌。 但是,如果要传递 JSON Web 令牌 (JWT),则必须使用Authorization: Bearer
。