从清单注册 GitHub 应用

关于 GitHub App 清单

Note

GitHub App 清单不适用于由企业拥有的 GitHub Apps。

从清单注册 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 API 扩展 GitHub App，而无需配置应用。
创建 GitHub App 参考设计，以便与 GitHub 社区共享。
确保使用相同的配置将 GitHub Apps 部署到开发和生产环境。
跟踪对 GitHub App 配置的修改。

实现 GitHub Apps 清单流

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

Note

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

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

将用户重定向到 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 参数中的应用的名称。如果你未在 manifest 中包含 name，他们可以在此字段中为应用设置自己的名称。

GitHub App 清单参数

名称	Type	说明
`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`	当 GitHub App 可供公众使用时，设置为 `true`；当它仅供应用的所有者访问时，设置为 `false`。
`default_events`	`array`	GitHub App 订阅的事件列表。
`default_permissions`	`object`	GitHub App 需要的权限集。对象的格式使用键的权限名称（例如 `issues`）和值的访问类型（例如 `write`）。有关详细信息，请参阅“为 GitHub Apps 选择权限”。
`request_oauth_on_install`	`boolean`	设置为 `true`，以请求用户在安装 GitHub App 后许可 GitHub App。
`setup_on_update`	`boolean`	设置为 `true`，以在用户更新 GitHub App 安装后，重定向到 `setup_url`。

hook_attributes 对象具有以下键。

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

参数

客户	Type	说明
`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 会使用代码参数中的临时 code 重定向回 redirect_url。例如：

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

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

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

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

要完成握手，请将 POST 请求中的临时 code 发送到从清单创建 GitHub App 终结点。响应将包括 id (GitHub App ID)、pem（私钥）和 webhook_secret。 GitHub 会自动为应用创建 Webhook 机密。您可以将这些值存储在应用程序服务器上的环境变量中。例如，如果应用使用 dotenv 来存储环境变量，则你应该将这些变量存储在应用的 .env 文件中。

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

Note

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

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 或在任何需要的位置托管。导航到托管应用的 URL 时，你会发现一个包含注册 GitHub App 按钮的网页，人们可以单击该按钮注册预配置的应用。

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

使用 Glitch 托管应用程序

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

从清单注册 GitHub 应用

本文内容