Skip to main content

此版本的 GitHub Enterprise 已停止服务 2022-06-03. 即使针对重大安全问题,也不会发布补丁。 要获得更好的性能、改进的安全性和新功能,请升级到 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 应用程序,并接收用于检索应用程序私钥、web 挂钩密钥和 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 应用程序清单参数

名称类型描述
name字符串GitHub 应用程序的名称。
url字符串必填。GitHub 应用程序的主页。
hook_attributes对象GitHub 应用程序 web 挂钩的配置
redirect_url字符串用户从清单启动 GitHub 应用创建后要重定向到的完整 URL。
callback_urls字符串数组在用户授权安装后重定向到的完整 URL。 您可以提供最多 10 个回叫 URL。
说明字符串GitHub 应用程序的说明。
public布尔值当 GitHub 应用程序可供公众使用时,设置为 true ;当它仅供应用程序的所有者访问时,设置为 false
default_events数组GitHub 应用程序订阅的事件列表。
default_permissions对象GitHub 应用程序所需的权限集。 对象的� �式使用键的权限名称(例如 issues)和值的访问类型(例如 write)。

hook_attributes 对象含有以下键:

名称类型描述
url字符串必填。将接收 web 挂钩 POST 请求的服务器的 URL。
active布尔值当此挂钩被触发时提供事件详细信息,默认值为 true。

参数

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

示例

此示例使用网页上的表单,其中包含一个按钮,该按钮可触发个人帐户的 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 将使用代� �参数中的临时 code 重定向回 redirect_url 。 例如:

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 应用程序所需的许多任务,例如验证 web 挂钩和执行身份验证。 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 托管应用程序

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