Skip to main content

此版本的 GitHub Enterprise 已停止服务 2022-10-12. 即使针对重大安全问题,也不会发布补丁。 为了获得更好的性能、更高的安全性和新功能,请升级到最新版本的 GitHub Enterprise。 如需升级帮助,请联系 GitHub Enterprise 支持

从清单创建 GitHub 应用程序

GitHub 应用程序清单是预先配置的 GitHub 应用程序,您可以与希望在其个人仓库中使用您的应用程序的任何用户分享它。 清单流程允许用户快速创建、安装和开始扩展 GitHub 应用程序,而� 需注册应用程序或将注册连接到托管应用代� �。

关于 GitHub 应用程序清单

当有人从清单创建 GitHub 应用程序时,他们只需遵循 URL 并命名应用程序即可。 清单包括自动注册应用程序所需的权限、事件和 web 挂钩 URL。 清单流程创建 GitHub 应用程序注册并检索应用程序的 web 挂钩密钥、私钥 (PEM 文件) 和 GitHub 应用程序 ID。 从清单创建应用的人将拥有该应用,并可以选择编辑应用的配置设置、� 除它或将其转让给 GitHub 上的其他人。

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

以下是您可以使用 GitHub 应用程序清单来创建预配置应用程序的一些场景:

  • 开发 GitHub 应用程序时,帮助新的团队成员快速上手。
  • 允许其他人使用 GitHub API 扩展 GitHub 应用程序,而� 需他们配置应用程序。
  • 创建 GitHub 应用程序参考设计,与 GitHub 社区分享。
  • 确保使用相同的配置将 GitHub 应用程序部署到开发和生产环境。
  • 跟踪对 GitHub 应用程序配置的修订。

实现 GitHub 应用程序清单流程

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

注意:必须在一小时内完成 GitHub 应用清单流中的所有三个步骤。

按照以下步骤实现 GitHub 应用程序清单流程:

  1. 将人员重定向到 GitHub 以创建新的 GitHub 应用程序。
  2. GitHub 将人员重定向回您的站点。
  3. 交换临时代� �以检索应用程序配置。

1. 将人员重定向到 GitHub 以创建新的 GitHub 应用

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

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

创建应用的人将被重定向到带有输入字段的 GitHub 页面,他们可以在该页面编辑� 包含在 manifest 参数中的应用的名称。 如果� 未在 manifest 中包含 name,他们可以在此字段中为应用设置自己的名称。

创建 GitHub 应用程序清单

GitHub 应用程序清单参数

名称类型说明
namestringGitHub 应用程序的名称。
urlstring必填。 GitHub 应用的主页。
hook_attributesobjectGitHub 应用程序 web 挂钩的配置
redirect_urlstring用户从清单启动 GitHub 应用创建后要重定向到的完整 URL。
callback_urlsarray of strings在用户授权安装后重定向到的完整 URL。 您可以提供最多 10 个回叫 URL。
descriptionstringGitHub 应用程序的说明。
publicboolean当 GitHub 应用可供公众使用时,设置为 true;当其仅可供应用所有者访问时,设置为 false
default_eventsarrayGitHub 应用订阅的事件列表。
default_permissionsobjectGitHub 应用所需的权限集。 对象的� �式使用键的权限名称(例如 issues)和值的访问类型(例如 write)。

hook_attributes 对象具有以下键:

名称类型说明
urlstring必填。 将接收 Webhook POST 请求的服务器的 URL。
activeboolean当此挂钩被触发时提供事件详细信息,默认值为 true。

参数

名称类型说明
statestring不可猜测的随机字符串。 它用于防止跨站请求伪� 攻击。

示例

此示例使用网页上的表单,其中包含一个按钮,该按钮可触发个人帐户的 POST 请求:

<form action="https://github.com/settings/apps/new?state=abc123" method="post">
 Create 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">
 Create 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 会自动为应用程序创建一个 web 挂钩密钥。 您可以将这些值存储在应用程序服务器上的环境变量中。 例如,如果应用使用 dotenv 来存储环境变量,则� 应该将这些变量存储在应用的 .env 文件中。

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

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

POST /app-manifests/{code}/conversions

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

清单流程的最后一步完成后,从流程创建应用程序的人将是注册 GitHub 应用程序的所有者,他们可以将其安装到他们的任何个人仓库中。 他们可以选择使用 GitHub API 扩展应用程序、将所有权转让给其他人或者随时� 除它。

使用 Probot 实现 GitHub 应用程序清单流程

Probot 是一种使用 Node.js 构建的框架,可执行所有 GitHub 应用所需的很多任务,例如验证 Webhook 和执行身份验证。 Probot 实现了 GitHub 应用清单流,使人们能够轻松创建 GitHub 应用参考设计并与 GitHub 社区共享。

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

  1. 生成新的 GitHub 应用
  2. 打开� 创建的项目,自定义 app.yml 文件中的设置。 Probot 使用 app.yml 中的设置作为 GitHub 应用清单参数
  3. 添� 应用程序的自定义代� �。
  4. 在本地运行 GitHub 应用,或将其托管到� 想要的任何位置。 导航到托管应用的 URL 时,� 会发现一个包含“注册 GitHub 应用”按钮的网页,人们可以单击该按钮创建预配置的应用。 下面的网页是 Probot 对 GitHub 应用清单流中的步骤 1 的实现:

注册 Probot GitHub 应用程序

Probot 使用 dotenv 创建一个 .env 文件,并使用从应用配置中检索的值设置 APP_IDPRIVATE_KEYWEBHOOK_SECRET 环境变量。

使用 Glitch 托管应用程序

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