从manifest文件注册GitHub应用

关于 GitHub App 清单

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

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

下面是一些方案，你可以使用 GitHub App 清单来注册预配置的应用：

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

实施 GitHub App Manifest 流

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

注意

必须在一小时内完成GitHub App清单流中的所有三个步骤。

按照以下步骤实现GitHub App清单流程：

你将人员重定向到 GitHub 去注册新的 GitHub App。

          GitHub 将人员重定向回您的站点。

交换临时代码以检索应用程序配置。

1. 你将人员重定向到 GitHub 去注册新的 GitHub App。

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

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

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

GitHub App Manifest 参数

名称	类型	说明
`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`	当你的`true`可供公众使用时，设置为GitHub App；当仅供应用所有者访问时，设置为`false`。
`default_events`	`array`
[
](/webhooks/webhook-events-and-payloads)订阅的GitHub App列表。
`default_permissions`	`object`	GitHub App所需的权限集。对象的格式使用键的权限名称（例如 `issues`）和值的访问类型（例如 `write`）。有关详细信息，请参阅“为GitHub应用选择权限”。若要查看可使用权限的列表及其参数化名称，请参阅管理个人访问令牌。
`request_oauth_on_install`	`boolean`	将`true`设置为在安装GitHub App之后，请求用户授权GitHub App。
`setup_on_update`	`boolean`	设置为 `true` 后将在用户更新 `setup_url` 安装后，将他们重定向到 GitHub App。

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">
 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 App 时，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 App 清单终结点。响应将包括 id （ID）、 GitHub App （私钥）和 pem``webhook_secret 。 GitHub 自动为应用程序创建 Webhook 密钥。您可以将这些值存储在应用程序服务器上的环境变量中。例如，如果应用使用 dotenv 来存储环境变量，则你应该将这些变量存储在应用的 .env 文件中。

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

注意

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

POST /app-manifests/{code}/conversions

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

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

使用 Probot 实现 GitHub App 清单流

Probot 是一个使用 Node.js 构建的框架，执行所有 GitHub Apps任务所需的许多任务，例如验证 Webhook 和执行身份验证。 Probot 实现 GitHub App 清单流，以便与社区轻松创建和共享 GitHub App 参考设计 GitHub 。

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

生成一个新 GitHub App。
打开你创建的项目，自定义 app.yml 文件中的设置。 Probot 使用 app.yml 中的设置作为 GitHub App清单参数。
添加应用程序的自定义代码。

          [在本地运行 GitHub App](https://probot.github.io/docs/development/#running-the-app-locally)或将其托管到你想要的任何位置。 导航到托管应用的 URL 时，你将找到一个网页，其中包含一个 **“注册 GitHub App** ”按钮，用户可以单击该按钮注册预配置的应用。

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

从manifest文件注册GitHub应用

在本文中