从清单创建 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 应用程序，并接收用于检索应用程序私钥、web 挂钩密钥和 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`	`字符串`	GitHub 应用程序的名称。
`url`	`字符串`	必填。GitHub 应用程序的主页。
`hook_attributes`	`对象`	GitHub 应用程序 web 挂钩的配置
`redirect_url`	`字符串`	在用户从清单创建 GitHub 应用程序后重定向到的完整 URL。
`callback_url`	`字符串`	在用户授权安装后重定向到的完整 URL。
`说明`	`字符串`	GitHub 应用程序的说明。
`public`	`布尔值`	当 GitHub 应用程序可供公众使用时，设置为 `true` ；当它仅供应用程序的所有者访问时，设置为 `false`。
`default_events`	`数组`	GitHub 应用程序订阅的事件列表。
`default_permissions`	`对象`	GitHub 应用程序所需的权限集。对象的� �式使用键的权限名称（例如 `issues`）和值的访问类型（例如 `write`）。

hook_attributes 对象含有以下键：

名称	类型	描述
`url`	`字符串`	必填。将接收 web 挂钩 `POST` 请求的服务器的 URL。
`active`	`布尔值`	当此挂钩被触发时提供事件详细信息，默认值为 true。

参数

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

示例

此示例使用网页上的表单，其中包含一个按钮，该按钮可触发用户帐户的 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_url": "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_url": "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. 交换临时代� �以检索应用程序配置

要完成握手，请在 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 应用程序所需的许多任务，例如验证 web 挂钩和执行身份验证。 Probot 实现 GitHub 应用程序清单流程，便于创建 GitHub 应用程序参考设计并与 GitHub 社区分享。

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

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

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

使用 Glitch 托管应用程序

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