从清单注册 GitHub 应用

关于 GitHub 应用清单

当用户从清单注册 GitHub 应用时，他们只需要遵循一个 URL 并命名该应用即可。清单包含自动注册应用所需的权限、事件和 Webhook URL。清单流程会创建 GitHub 应用注册，并生成应用的 Webhook 密钥、私钥（PEM 文件）、客户端密钥和 GitHub 应用 ID。从清单创建 GitHub 应用注册的人员将拥有该 GitHub 应用注册，可以选择编辑注册设置、删除它或将其转移给 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，或向组织帐户发送 POST 请求到 https://github.com/organizations/ORGANIZATION/settings/apps/new，并将 ORGANIZATION 替换为将注册应用的组织帐户的名称。

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

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

GitHub 应用清单参数

名称	类型	描述
`name`	`字符串`	GitHub 应用的名称。
`url`	`字符串`	必需。您的 GitHub 应用的主页。
`hook_attributes`	`对象`	GitHub 应用 Webhook 的配置。
`redirect_url`	`字符串`	用户从清单启动 GitHub 应用注册后重定向到的完整 URL。
`callback_urls`	`字符串数组`	用户授权安装后重定向到的完整 URL。您可以提供最多 10 个回调 URL。
`setup_url`	`字符串`	如果需要其他设置，则在用户安装您的 GitHub 应用后重定向用户的完整 URL。
`description`	`字符串`	GitHub 应用的描述。
`public`	`布尔值`	当您的 GitHub 应用可供公众使用时设置为 `true`，当它仅供应用所有者访问时设置为 `false`。
`default_events`	`数组`	GitHub 应用订阅的事件列表。
`default_permissions`	`对象`	GitHub 应用所需的权限集。对象的格式使用权限名称作为键（例如，`issues`），使用访问类型作为值（例如，`write`）。有关更多信息，请参阅“为 GitHub 应用选择权限”。
`request_oauth_on_install`	`布尔值`	安装 GitHub 应用后，设置为 `true` 以请求用户授权 GitHub 应用。
`setup_on_update`	`布尔值`	在用户更新您的 GitHub 应用安装后，设置为 `true` 以将用户重定向到 `setup_url`。

hook_attributes 对象具有以下键。

名称	类型	描述
`url`	`字符串`	必需。将接收 Webhook `POST` 请求的服务器的 URL。
`active`	`布尔值`	触发此钩子时传递事件详细信息，默认为 true。

参数

名称	类型	描述
`state`	`字符串`	一个不可猜测的随机字符串。它用于防止跨站点请求伪造攻击。

示例

此示例使用网页上的表单，其中包含一个触发个人帐户 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 会将代码参数中的临时code重定向回redirect_url。例如：

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

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

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

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

要完成握手，请将临时code以POST请求发送到从清单创建 GitHub 应用端点。响应将包含id（GitHub 应用 ID）、pem（私钥）和webhook_secret。GitHub 会自动为应用创建一个 Webhook 密钥。您可以将这些值存储在应用服务器上的环境变量中。例如，如果您的应用使用 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 应用**按钮，用户可以点击该按钮来注册预配置的应用。

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

使用 Glitch 托管您的应用

您可以看到一个示例 Probot 应用，它使用 Glitch 来托管和共享该应用。该示例使用 Checks API，并在 app.yml 文件中选择必要的 Checks API 事件和权限。Glitch 是一种允许您“自行重新组合”应用的工具。重新组合应用会创建 Glitch 托管和部署的应用副本。请参阅“关于 Glitch”，了解有关重新组合 Glitch 应用的信息。

本文内容