从清单注册 GitHub 应用

关于 GitHub 应用清单

当用户从清单注册 GitHub 应用时，他们只需要按照 URL 并命名应用即可。清单包含自动注册应用所需的权限、事件和 Webhook URL。清单流程创建 GitHub 应用注册并生成应用的 Webhook 密钥、私钥（PEM 文件）、客户端密钥和 GitHub 应用 ID。从清单创建 GitHub 应用注册的用户将拥有 GitHub 应用注册，并可以选择编辑注册的设置、删除它或将其转移到 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 应用程序，提供一个链接，让他们点击该链接，向 https://github.com/settings/apps/new（个人帐户）或 https://github.com/organizations/ORGANIZATION/settings/apps/new（组织帐户）发送 POST 请求，将 ORGANIZATION 替换为应用程序将注册到的组织帐户的名称。

您必须将 GitHub 应用程序清单参数作为 JSON 编码的字符串包含在名为 manifest 的参数中。您还可以包含一个 state 参数以增强安全性。

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

GitHub 应用程序清单参数

名称	类型	描述
`name`	`字符串`	GitHub 应用程序的名称。
`url`	`字符串`	必需。 GitHub 应用程序的主页。
`hook_attributes`	`对象`	GitHub 应用程序 Webhook 的配置。
`redirect_url`	`字符串`	用户从清单中启动 GitHub 应用程序注册后重定向到的完整 URL。
`callback_urls`	`字符串数组`	用户授权安装后重定向到的完整 URL。您可以提供最多 10 个回调 URL。
`setup_url`	`字符串`	用户安装 GitHub 应用程序后，如果需要进行其他设置，则会将用户重定向到的完整 URL。
`description`	`字符串`	GitHub 应用程序的描述。
`public`	`布尔值`	当您的 GitHub 应用程序对公众可用时设置为 `true`，当它仅对应用程序所有者可用时设置为 `false`。
`default_events`	`数组`	GitHub 应用程序订阅的事件列表。
`default_permissions`	`对象`	GitHub 应用所需的权限集。对象的格式使用权限名称作为键（例如，`issues`），使用访问类型作为值（例如，`write`）。有关更多信息，请参阅“为 GitHub 应用选择权限”。
`request_oauth_on_install`	`布尔值`	设置为 `true` 以在安装 GitHub 应用后请求用户授权该应用。
`setup_on_update`	`布尔值`	设置为 `true` 以在用户更新您的 GitHub 应用安装后将他们重定向到 `setup_url`。

hook_attributes 对象具有以下键。

名称	类型	描述
`url`	`字符串`	必需。将接收 webhook `POST` 请求的服务器的 URL。
`active`	`布尔值`	在触发此钩子时传递事件详细信息，默认为 true。

参数

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

示例

此示例使用网页上的表单，该表单包含一个按钮，该按钮会触发个人帐户的 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 应用时，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 会自动为应用创建 webhook 密钥。您可以将这些值存储在应用服务器上的环境变量中。例如，如果您的应用使用 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 应用 按钮的网页，人们可以点击该按钮注册预配置的应用。

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

在 Glitch 上托管您的应用

您可以查看一个示例 Probot 应用，它使用Glitch来托管和共享该应用。该示例使用Checks API，并在 app.yml 文件中选择必要的 Checks API 事件和权限。Glitch 是一种允许您“重混自己的”应用的工具。重混一个应用会创建一个 Glitch 托管和部署的应用副本。请参阅“关于 Glitch”以了解有关重混 Glitch 应用的信息。

从清单注册 GitHub 应用

本文内容