从清单注册 GitHub 应用

关于 GitHub 应用程序清单

当有人从清单注册 GitHub 应用时，他们只需遵循 URL 并命名应用即可。清单包括自动注册应用程序所需的权限、事件和 web 挂钩 URL。清单流创建 GitHub 应用注册并生成应用的 Webhook 密钥、私钥（PEM 文件）和 GitHub 应用 ID。从清单创建 GitHub App 注册的人员将拥有 GitHub App 注册，并且可以选择编辑注册的设置、删除注册或将其转移给 GitHub 上的其他人。

可以使用 Probot 开始使用 GitHub 应用清单或查看示例实现。有关详细信息，请参阅“使用 Probot 实现 GitHub 应用清单流”。

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

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

实现 GitHub 应用程序清单流程

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

注意：必须在一小时内完成 GitHub 应用清单流中的所有三个步骤。

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

将人员重定向到 GitHub 以注册新的 GitHub 应用。
GitHub 将人员重定向回您的站点。
交换临时代码以检索应用程序配置。

1. 将人员重定向到 GitHub 以注册新的 GitHub 应用

若要重定向人员以注册新的 GitHub 应用，请为他们提供一个链接以供单击，该链接针对个人帐户将 POST 请求发送到 https://github.com/settings/apps/new，或针对组织帐户将该请求发送到 https://github.com/organizations/ORGANIZATION/settings/apps/new，并将 ORGANIZATION 替换为将注册应用的组织帐户的名称。

必须将 GitHub 应用清单参数作为 JSON 编码的字符串包含在名为 manifest 的参数中。还可以包含一个 state 参数以实现额外的安全性。

注册应用的人员将被重定向到带有输入字段的 GitHub 页面，他们可以在该页面编辑你包含在 manifest 参数中的应用的名称。如果你未在 manifest 中包含 name，他们可以在此字段中为应用设置自己的名称。

GitHub 应用程序清单参数

名称	Type	说明
`name`	`string`	GitHub App 的名称。
`url`	`string`	必填。 GitHub App 的主页。
`hook_attributes`	`object`	GitHub App 的 Webhook 的配置。
`redirect_url`	`string`	用户从清单开始注册 GitHub App 后要重定向到的完整 URL。
`callback_urls`	`array of strings`	在用户授权安装后重定向到的完整 URL。您可以提供最多 10 个回叫 URL。
`setup_url`	`string`	用户安装 GitHub App 后要重定向到的完整 URL（如果需要额外设置）。
`description`	`string`	GitHub App 的说明。
`public`	`boolean`	当 GitHub App 可供公众使用时，设置为 `true`；当它仅供应用的所有者访问时，设置为 `false`。
`default_events`	`array`	GitHub App 订阅的事件列表。
`default_permissions`	`object`	GitHub 应用所需的权限集。对象的格式使用键的权限名称（例如 `issues`）和值的访问类型（例如 `write`）。有关详细信息，请参阅“为 GitHub Apps 选择权限”。
`request_oauth_on_install`	`boolean`	设置为 `true`，以请求用户在安装 GitHub App 后许可 GitHub App。
`setup_on_update`	`boolean`	设置为 `true`，以在用户更新 GitHub App 安装后，重定向到 `setup_url`。

hook_attributes 对象具有以下键。

名称	Type	说明
`url`	`string`	必填。将接收 Webhook `POST` 请求的服务器的 URL。
`active`	`boolean`	当此挂钩被触发时提供事件详细信息，默认值为 true。

参数

客户	Type	说明
`state`	`string`	不可猜测的随机字符串。它用于防止跨站请求伪造攻击。

示例

此示例使用网页上的表单，其中包含一个按钮，该按钮可触发个人帐户的 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 将人员重定向回你的站点

当人员单击“创建 GitHub 应用”时，GitHub 会重定向回 redirect_url，其中，代码参数中包含临时 code。例如：

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

如果提供了 state 参数，则还将在 redirect_url 中看到该参数。例如：

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

3. 交换临时代码以检索应用配置

若要完成握手，请将 POST 请求中的临时 code 发送到从清单创建 GitHub 应用终结点。响应将包括 id（GitHub 应用 ID）、pem（私钥）和 webhook_secret。 GitHub 会自动为应用程序创建一个 web 挂钩密钥。您可以将这些值存储在应用程序服务器上的环境变量中。例如，如果应用使用 dotenv 来存储环境变量，则你应该将这些变量存储在应用的 .env 文件中。

您必须在一小时内完成 GitHub 应用程序清单流程中的此步骤。

注意：此终结点具有速率限制。请参阅速率限制，了解如何获取当前速率限制状态。

POST /app-manifests/{code}/conversions

有关终结点响应的详细信息，请参阅从清单创建 GitHub 应用。

完成清单流的最后一步后，从流程注册应用的人员将是注册的 GitHub 应用的所有者，他们可以将应用安装到其任何个人存储库中。他们可以选择使用 GitHub API 扩展应用程序、将所有权转让给其他人或者随时删除它。

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

Probot 是一种使用 Node.js 构建的框架，可执行所有 GitHub 应用所需的很多任务，例如验证 Webhook 和执行身份验证。 Probot 实现了 GitHub 应用清单流，使人们能够轻松创建 GitHub 应用参考设计并与 GitHub 社区共享。

要创建可以分享的 Probot 应用程序，请遵循以下步骤：

生成新的 GitHub 应用。
打开你创建的项目，自定义 app.yml 文件中的设置。 Probot 使用 app.yml 中的设置作为 GitHub 应用清单参数。
添加应用程序的自定义代码。
在本地运行 GitHub 应用，或将其托管到你想要的任何位置。导航到托管应用的 URL 时，你会发现一个包含“注册 GitHub 应用”按钮的网页，人们可以单击该按钮注册预配置的应用。

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

使用 Glitch 托管应用程序

可以看到一个示例 Probot 应用，该应用使用 Glitch 来托管和共享应用。该示例使用检查 API，并选择 app.yml 文件中必要的检查 API 事件和权限。 Glitch 是一个允许您“重新组合自己的”应用程序的工具。重新组合应用程序将创建一个 Glitch 托管和部署的应用程序副本。请参阅“关于 Glitch”，了解如何重新组合 Glitch 应用。

从清单注册 GitHub 应用

本文内容