从清单注册 GitHub 应用

关于 GitHub 应用清单

当有人从清单注册 GitHub 应用时，只需访问一个 URL 并为应用命名即可。清单中包含了自动注册应用所需的权限、事件和 webhook URL。清单流程会创建 GitHub 应用注册并生成应用的 webhook 密钥、私钥（PEM 文件）、客户端密钥和 GitHub 应用 ID。通过清单创建注册的用户将拥有该 GitHub 应用的所有权，并可以编辑注册设置、删除或将其转让给 GitHub 上的其他人。

您可以使用 Probot 入门 GitHub 应用清单，或查看示例实现。请参阅使用 Probot 实现 GitHub 应用清单流程了解更多信息。

以下是您可能使用 GitHub 应用清单注册预配置应用的一些场景

帮助新团队成员在开发 GitHub 应用时快速上手。
允许他人使用 GitHub API 扩展 GitHub 应用，而无需他们自行配置应用。
创建 GitHub 应用参考设计以分享给 GitHub 社区。
确保在开发和生产环境中使用相同的配置部署 GitHub 应用。
跟踪 GitHub 应用配置的修订。

实现 GitHub 应用清单流程

GitHub 应用清单流程使用类似于 OAuth 流程的握手过程。该流程使用清单来注册 GitHub 应用，并收到一个临时的 code，用于检索应用的私钥、webhook 密钥和 ID。

注意

您必须在一小时内完成 GitHub 应用清单流程的全部三步。

按照以下步骤实现 GitHub 应用清单流程

您将用户重定向至 GitHub 注册新的 GitHub 应用。
GitHub 将用户重定向回您的站点。
您使用临时代码交换以获取应用配置。

1. 您将用户重定向至 GitHub 注册新的 GitHub 应用

要将用户重定向至注册新 GitHub 应用，请提供一个链接，让他们点击后向 https://github.com/settings/apps/new（个人账户）或 https://github.com/organizations/ORGANIZATION/settings/apps/new（组织账户）发送 POST 请求，将 ORGANIZATION 替换为要注册应用的组织账户名称。

您必须在名为 manifest 的参数中以 JSON 编码的字符串形式包含 GitHub 应用清单参数。您还可以包含 state 参数以增强安全性。

注册该应用的人将被重定向到 GitHub 页面，其中有一个输入字段可编辑您在 manifest 参数中包含的应用名称。如果您未在 manifest 中提供 name，他们可以在此字段自行设置应用名称。

GitHub 应用清单参数

名称	类型	描述
`name`	`string`	GitHub 应用的名称。
`url`	`string`	必填。您的 GitHub 应用的主页。
`hook_attributes`	`object`	GitHub 应用 webhook 的配置。
`redirect_url`	`string`	用户发起从清单注册 GitHub 应用后要重定向的完整 URL。
`callback_urls`	`字符串数组`	在某人授权安装后要重定向的完整 URL。最多可提供 10 个回调 URL。
`setup_url`	`string`	如果需要额外设置，用户安装您的 GitHub 应用后要重定向的完整 URL。
`description`	`string`	GitHub 应用的描述。
`public`	`boolean`	当您的 GitHub 应用对公众开放时设为 `true`，仅对应用所有者可用时设为 `false`。
`default_events`	`数组 (array)`	GitHub 应用订阅的事件列表。
`default_permissions`	`object`	GitHub 应用所需的权限集合。对象的格式使用权限名称作为键（例如 `issues`），访问类型作为值（例如 `write`）。更多信息请参阅为 GitHub 应用选择权限。要查看可用权限列表及其参数化名称，请参阅管理个人访问令牌。
`request_oauth_on_install`	`boolean`	在 GitHub 应用安装后设为 `true`，以请求用户授权该应用。
`setup_on_update`	`boolean`	在用户更新您的 GitHub 应用安装后设为 `true`，以将其重定向至 `setup_url`。

hook_attributes 对象包含以下键。

名称	类型	描述
`url`	`string`	必填。接收 webhook `POST` 请求的服务器 URL。
`active`	`boolean`	当此钩子被触发时发送事件详情，默认 true。

参数

名称	类型	描述
`状态`	`string`	不可猜测的随机字符串，用于防御跨站请求伪造（CSRF）攻击。

示例

此示例在网页上使用表单和按钮，以触发针对个人账户的 POST 请求

<form action="https://github.com/settings/apps/new?state=abc123" method="post">
 Register a GitHub App Manifest: <input type="text" name="manifest" id="manifest"><br>
 <input type="submit" value="Submit">
</form>

<script>
 input = document.getElementById("manifest")
 input.value = JSON.stringify({
   "name": "Octoapp",
   "url": "https://www.example.com",
   "hook_attributes": {
     "url": "https://example.com/github/events",
   },
   "redirect_url": "https://example.com/redirect",
   "callback_urls": [
     "https://example.com/callback"
   ],
   "public": true,
   "default_permissions": {
     "issues": "write",
     "checks": "write"
   },
   "default_events": [
     "issues",
     "issue_comment",
     "check_suite",
     "check_run"
   ]
 })
</script>

此示例在网页上使用表单和按钮，以触发针对组织账户的 POST 请求。将 ORGANIZATION 替换为您想要注册应用的组织账户名称。

<form action="https://github.com/organizations/ORGANIZATION/settings/apps/new?state=abc123" method="post">
 register a GitHub App Manifest: <input type="text" name="manifest" id="manifest"><br>
 <input type="submit" value="Submit">
</form>

<script>
 input = document.getElementById("manifest")
 input.value = JSON.stringify({
   "name": "Octoapp",
   "url": "https://www.example.com",
   "hook_attributes": {
     "url": "https://example.com/github/events",
   },
   "redirect_url": "https://example.com/redirect",
   "callback_urls": [
     "https://example.com/callback"
   ],
   "public": true,
   "default_permissions": {
     "issues": "write",
     "checks": "write"
   },
   "default_events": [
     "issues",
     "issue_comment",
     "check_suite",
     "check_run"
   ]
 })
</script>

2. GitHub 将用户重定向回您的站点

当用户点击 Create GitHub App 时，GitHub 会将其重定向回 redirect_url，并在 code 参数中附带临时的 code。例如

https://example.com/redirect?code=a180b1a3d263c81bc6441d7b990bae27d4c10679

如果您提供了 state 参数，您同样会在 redirect_url 中看到该参数。例如

https://example.com/redirect?code=a180b1a3d263c81bc6441d7b990bae27d4c10679&state=abc123

3. 您使用临时代码交换以获取应用配置

要完成握手，请将临时的 code 通过 POST 请求发送至 Create a GitHub App from a manifest 端点。响应中将包含 id（GitHub 应用 ID）、pem（私钥）和 webhook_secret。GitHub 会自动为应用创建 webhook 密钥。您可以将这些值存储在应用服务器的环境变量中。例如，如果您的应用使用 dotenv 来存放环境变量，您可以将它们写入应用的 .env 文件。

您必须在一小时内完成此步骤。

注意

此端点受速率限制。请参阅速率限制了解如何获取当前的速率限制状态。

POST /app-manifests/{code}/conversions

有关端点响应的更多信息，请参阅 Create a GitHub App from a manifest。

当清单流程的最后一步完成后，从该流程注册应用的人员将成为已注册 GitHub 应用的所有者，且可以在其任何账户上安装该应用。他们可以选择使用 GitHub API 扩展应用、将所有权转让给其他人，或随时删除该应用。

使用 Probot 实现 GitHub 应用清单流程

Probot 是一个基于 Node.js 构建的框架，负责处理所有 GitHub 应用所需的常见任务，如验证 webhook 与执行身份验证。Probot 实现了 GitHub 应用清单流程，使得创建并向 GitHub 社区分享 GitHub 应用参考设计变得轻而易举。

要创建可共享的 Probot 应用，请按以下步骤操作

生成一个新的 GitHub 应用.
打开您创建的项目，并在 app.yml 文件中自定义设置。Probot 将 app.yml 中的设置用作 GitHub 应用清单参数。
添加您应用的自定义代码。
在本地运行 GitHub 应用或将其托管在任意您喜欢的地方。当您访问托管应用的 URL 时，会看到一个带有 Register GitHub App 按钮的网页，用户可点击该按钮注册预配置的应用。

使用 dotenv，Probot 会创建一个 .env 文件，并将 APP_ID、PRIVATE_KEY 与 WEBHOOK_SECRET 环境变量设置为从应用配置中检索到的值。

使用 Glitch 托管您的应用

您可以查看一个使用 Glitch 托管并分享的示例 Probot 应用。该示例使用 Checks API，并在 app.yml 文件中选择了所需的 Checks API 事件和权限。Glitch 是一个让您“Remix 您自己的”应用的工具。Remix 应用会创建该应用的副本，由 Glitch 托管并部署。请参阅关于 Glitch 了解如何 Remix Glitch 应用。

本文内容