# 从manifest文件注册GitHub应用

预配置的GitHub App 注册可以通过一个GitHub App 清单与其他用户共享。 清单流程允许某人快速注册 GitHub App。

## 关于 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](https://probot.github.io/) 开始使用GitHub App清单或查看示例实现。 有关详细信息，请参阅“使用 Probot 实现清单流”。[GitHub App](#using-probot-to-implement-the-github-app-manifest-flow)

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

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

## 实施 GitHub App Manifest 流

GitHub App清单流使用类似于[ OAuth 流的握手过程](/zh/enterprise-server@3.22/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps)。 该流使用清单[注册 GitHub App](/zh/enterprise-server@3.22/apps/creating-github-apps/registering-a-github-app/registering-a-github-app)，并接收用于检索该应用的私钥、Webhook 机密和 ID 的临时 `code`。

> \[!NOTE] 必须在一小时内完成GitHub App清单流中的所有三个步骤。

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

1. 你将人员重定向到 GitHub 去注册新的 GitHub App。
2. GitHub 将人员重定向回您的站点。
3. 交换临时代码以检索应用程序配置。

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

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

必须将 [GitHub App清单参数](#github-app-manifest-parameters)作为 JSON 编码的字符串包含在名为 `manifest` 的参数中。 还可以包含一个 `state`[参数](#parameters)以实现额外的安全性。

注册应用的人员将重定向到包含 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应用选择权限](/zh/enterprise-server@3.22/apps/creating-github-apps/registering-a-github-app/choosing-permissions-for-a-github-app)”。 若要查看可使用权限的列表及其参数化名称，请参阅 [管理个人访问令牌](/zh/enterprise-server@3.22/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#account-permissions)。 |                    |                                                        |
| `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` 请求：

```html
<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` 替换为要在其中注册应用的组织帐户的名称。

```html
<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. 交换临时代码以检索应用配置

若要完成握手，请将`code` 请求中的临时 `POST` 发送到[创建GitHub App 清单](/zh/enterprise-server@3.22/rest/apps/apps#create-a-github-app-from-a-manifest)终结点。 响应将包括 `id` （ID）、 GitHub App （私钥）和 `pem``webhook_secret` 。
GitHub 自动为应用程序创建 Webhook 密钥。 您可以将这些值存储在应用程序服务器上的环境变量中。 例如，如果应用使用 [dotenv](https://github.com/bkeepers/dotenv) 来存储环境变量，则你应该将这些变量存储在应用的 `.env` 文件中。

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

> \[!NOTE]
> 此终结点具有速率限制。 请参阅[速率限制](/zh/enterprise-server@3.22/rest/rate-limit/rate-limit)，了解如何获取当前速率限制状态。

```
POST /app-manifests/{code}/conversions
```

有关终结点响应的详细信息，请参阅[从清单创建GitHub App](/zh/enterprise-server@3.22/rest/apps/apps#create-a-github-app-from-a-manifest)。

当清单流中的最后一步完成时，从流中注册应用程序的人员将成为已注册的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 应用程序，请遵循以下步骤：

1. [生成一个新 GitHub App](https://probot.github.io/docs/development/#generating-a-new-app)。
2. 打开你创建的项目，自定义 `app.yml` 文件中的设置。 Probot 使用 `app.yml` 中的设置作为 [GitHub App清单参数](#github-app-manifest-parameters)。
3. 添加应用程序的自定义代码。
4. [在本地运行 GitHub App](https://probot.github.io/docs/development/#running-the-app-locally)或将其托管到你想要的任何位置。 导航到托管应用的 URL 时，你将找到一个网页，其中包含一个 **“注册 GitHub App** ”按钮，用户可以单击该按钮注册预配置的应用。

Probot 使用 [dotenv](https://github.com/bkeepers/dotenv) 创建一个 `.env` 文件，并将从应用配置中获取的`APP_ID`用来设置`PRIVATE_KEY`、`WEBHOOK_SECRET` 和 [](#3-you-exchange-the-temporary-code-to-retrieve-the-app-configuration) 环境变量。