从清单创建 GitHub 应用程序

关于 GitHub 应用程序清单

当有人从清单创建 GitHub 应用程序时，他们只需遵循 URL 并命名应用程序即可。清单包括自动注册应用程序所需的权限、事件和 web 挂钩 URL。清单流程创建 GitHub 应用程序注册并检索应用程序的 web 挂钩密钥、私钥（PEM 文件）和 GitHub 应用程序 ID。从清单创建应用的人将拥有该应用，并可以选择编辑应用的配置设置、� 除它或将其转让给 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 应用程序清单

GitHub 应用程序清单参数

名称	类型	说明
`name`	`string`	GitHub 应用程序的名称。
`url`	`string`	必填。 GitHub 应用的主页。
`hook_attributes`	`object`	GitHub 应用程序 web 挂钩的配置
`redirect_url`	`string`	用户从清单启动 GitHub 应用创建后要重定向到的完整 URL。
`callback_urls`	`array of strings`	在用户授权安装后重定向到的完整 URL。您可以提供最多 10 个回叫 URL。
`description`	`string`	GitHub 应用程序的说明。
`public`	`boolean`	当 GitHub 应用可供公众使用时，设置为 `true`；当其仅可供应用所有者访问时，设置为 `false`。
`default_events`	`array`	GitHub 应用订阅的事件列表。
`default_permissions`	`object`	GitHub 应用所需的权限集。对象的� �式使用键的权限名称（例如 `issues`）和值的访问类型（例如 `write`）。

hook_attributes 对象具有以下键：

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

参数

名称	类型	说明
`state`	`string`	不可猜测的随机字符串。它用于防止跨站请求伪� 攻击。

示例

此示例使用网页上的表单，其中包含一个按钮，该按钮可触发个人帐户的 POST 请求：

<form action="https://github.com/settings/apps/new?state=abc123" method="post">
 Create 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">
 Create 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 对 GitHub 应用清单流中的步骤 1 的实现：

注册 Probot GitHub 应用程序

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

使用 Glitch 托管应用程序

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