从manifest文件注册GitHub应用

关于 GitHub App 清单文件

注意

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社区共享的GitHub App参考设计。
确保使用相同的配置将GitHub Apps部署到开发和生产环境。
跟踪 GitHub App 配置的修订。

实施 GitHub App Manifest 流程

ManifestGitHub 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请求以创建组织帐户，并将ORGANIZATION替换为将在其中注册应用的组织帐户名称。

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

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

          GitHub App Manifest参数

名称	类型	说明
`name`	`string`

          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](https://probot.github.io/) 是一个使用 [Node.js](https://nodejs.org/) 构建的框架，执行所有 GitHub Apps任务所需的许多任务，例如验证 Webhook 和执行身份验证。 Probot 实现 [GitHub App 清单流](#implementing-the-github-app-manifest-flow)，以便与社区轻松创建和共享 GitHub App 参考设计 GitHub 。

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

       [生成一个新 GitHub App](https://probot.github.io/docs/development/#generating-a-new-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 和环境变量。

在本文中