构建 GitHub Apps 快速入门

快速构建一个在拉取请求中添加评论的 GitHub 应用。

本文内容

简介

GitHub 应用允许你自动化流程或将其他平台与 GitHub 集成。更多信息，请参阅“关于创建 GitHub 应用”。

本快速入门指南介绍了如何快速创建一个 GitHub 应用。当在应用已获得访问权限的仓库中打开拉取请求时，该应用会向拉取请求添加一条评论。

本快速入门指南使用预先编写的代码来帮助你快速入门。有关帮助你编写代码的更详细教程，请参阅“构建响应 Webhook 事件的 GitHub 应用”。

先决条件

你的计算机或 Codespace 应使用 Node.js 版本 12 或更高版本。更多信息，请参阅 Node.js。

步骤 1：克隆应用代码

为了帮助你快速入门，我们编写了一些你可以使用的代码。如果你想学习如何自己编写代码，请参阅“构建响应 Webhook 事件的 GitHub 应用”。

  1. 克隆 github/github-app-js-sample 仓库。更多信息，请参阅“克隆仓库”。你可以使用本地克隆或 GitHub Codespaces。
  2. 在终端窗口中，导航到存储克隆的目录。
  3. 运行 npm install 来安装依赖项。

步骤 2：获取 Webhook 代理 URL

为了在本地开发你的应用，你可以使用 Webhook 代理 URL 将 Webhook 从 GitHub 转发到你的计算机或 Codespace。本快速入门指南使用 Smee.io 提供 Webhook 代理 URL 并转发 Webhook。

  1. 在你的浏览器中，导航到 https://smee.io/。
  2. 点击启动新通道。
  3. 复制“Webhook 代理 URL”下的完整 URL。你将在后续步骤中使用此 URL。

步骤 3：注册 GitHub 应用

以下步骤将指导你配置本快速入门指南所需的应用设置。有关这些设置的更多信息，请参阅“注册 GitHub 应用”。

  1. 在 GitHub 上任何页面的右上角，点击你的个人资料照片。
  2. 导航到你的帐户设置。
    • 对于个人帐户拥有的应用，点击设置。
    • 对于组织拥有的应用
      1. 点击你的组织。
      2. 在组织的右侧，点击设置。
  3. 在左侧边栏中，点击 开发者设置。
  4. 在左侧边栏中，点击GitHub 应用。
  5. 点击新建 GitHub 应用。
  6. 在“GitHub 应用名称”下，输入你的应用名称。例如，USERNAME-quickstart-app，其中 USERNAME 是你的 GitHub 用户名。
  7. 在“主页 URL”下，输入 https://github.com/github/github-app-js-sample#readme。
  8. 对于本快速入门指南，跳过“识别和授权用户”和“安装后”部分。有关这些设置的更多信息，请参阅“注册 GitHub 应用”。
  9. 确保在“Webhook”下选择了启用。
  10. 在“Webhook URL”下，输入你之前的 Webhook 代理 URL。更多信息，请参阅“步骤 2：获取 Webhook 代理 URL”。
  11. 在“Webhook 密钥”下，输入一个随机字符串。你将在稍后使用此字符串。
  12. 在“仓库权限”下，“拉取请求”旁边，选择读写。
  13. 在“订阅事件”下，选择拉取请求。
  14. 在“此 GitHub 应用可在何处安装？”下，选择仅限此帐户。
  15. 点击创建 GitHub 应用。

步骤 4：存储识别信息和凭据

在本快速入门指南中，你将把应用的凭据和识别信息作为环境变量存储在 .env 文件中。部署应用时，你将需要更改存储凭据的方式。更多信息，请参阅“部署你的应用”。

在执行这些步骤之前，请确保你处于安全机器上，因为你将在本地存储你的凭据。

创建 .env 文件

你克隆的仓库在 .gitignore 文件中包含 .env。这将防止你意外提交应用的凭据。有关 .gitignore 文件的更多信息，请参阅“忽略文件”。

  1. 导航到存储 github/github-app-js-sample 克隆的目录。

  2. 在此目录的顶层创建一个名为 .env 的文件。

  3. 将以下内容添加到你的 .env 文件中。你将在后续步骤中更新这些值。

    文本
    APP_ID="YOUR_APP_ID"
WEBHOOK_SECRET="YOUR_WEBHOOK_SECRET"
PRIVATE_KEY_PATH="YOUR_PRIVATE_KEY_PATH"

如果你在创建应用后离开了应用设置页面，请导航到你的应用设置页面。

  1. 在 GitHub 上任何页面的右上角，点击你的个人资料照片。
  2. 导航到你的帐户设置。
    • 对于个人帐户拥有的应用，点击设置。
    • 对于组织拥有的应用
      1. 点击你的组织。
      2. 在组织的右侧，点击设置。
  3. 在左侧边栏中，点击 开发者设置。
  4. 在左侧边栏中，点击GitHub 应用。
  5. 在你的应用名称旁边，点击编辑。

获取你的应用凭据和识别信息

  1. 在你的应用设置页面上，“应用 ID”旁边，找到你的应用的应用 ID。
  2. 在你的 .env 文件中，将 YOUR_APP_ID 替换为你的应用的应用 ID。
  3. 在你的应用设置页面上，“私钥”下，点击生成私钥。你将看到一个 PEM 格式的私钥下载到你的计算机上。更多信息，请参阅“管理 GitHub 应用的私钥”。
  4. 如果你使用的是 Codespace，请将下载的 PEM 文件移动到你的 Codespace 中，以便你的 Codespace 可以访问该文件。
  5. 在你的 .env 文件中，将 YOUR_PRIVATE_KEY_PATH 替换为你的私钥的完整路径，包括 .pem 扩展名。
  6. 在你的 .env 文件中，将 YOUR_WEBHOOK_SECRET 替换为你的应用的 Webhook 密钥。如果你忘记了你的 Webhook 密钥，在“Webhook 密钥（可选）”下，点击更改密钥。输入新的密钥，然后点击保存更改。

步骤 5：安装你的应用

为了使你的应用能够在仓库的拉取请求中留下评论，它必须安装在拥有该仓库并被授予对该仓库访问权限的帐户上。由于你的应用是私有的，它只能安装在拥有该应用的帐户上。

  1. 在拥有你创建的应用的帐户中，创建一个新的仓库来安装该应用。更多信息，请参阅“创建新的仓库”。
  2. 如果你在创建应用后离开了应用设置页面，请导航到你的应用设置页面。更多信息，请参阅“导航到你的应用设置”。
  3. 点击公共页面。
  4. 点击安装。
  5. 选择仅选择仓库。
  6. 选择选择仓库下拉菜单，然后点击你在本节开头选择的仓库。
  7. 点击安装。

步骤 6：启动你的服务器

为了进行测试，你将使用你的计算机或 Codespace 作为服务器。你的应用只有在服务器运行时才会处于活动状态。

  1. 在终端窗口中，导航到存储 github/github-app-js-sample 克隆的目录。

  2. 要接收来自 Smee.io 的转发 Webhook，请运行 npx smee -u WEBHOOK_PROXY_URL -t https://127.0.0.1:3000/api/webhook。将 WEBHOOK_PROXY_URL 替换为你的 Webhook 代理 URL。如果你忘记了你的 URL，你可以在应用设置页面的“Webhook URL”字段中找到它。

    你应该会看到如下所示的输出，其中 WEBHOOK_PROXY_URL 是你的 Webhook 代理 URL

    Forwarding WEBHOOK_PROXY_URL to https://127.0.0.1:3000/api/webhook
Connected WEBHOOK_PROXY_URL

  3. 在第二个终端窗口中，导航到存储 github/github-app-js-sample 克隆的目录。

  4. 运行 npm run server。你的终端应该显示 Server is listening for events at: https://127.0.0.1:3000/api/webhook。

步骤 7：测试你的应用

现在你的服务器正在运行并接收转发的 Webhook 事件，通过打开拉取请求来测试你的应用。

  1. 在你在 步骤 5：安装你的应用 中创建的仓库上打开一个拉取请求。更多信息，请参阅“创建拉取请求”。
  2. 导航到 smee.io 上的 Webhook 代理 URL。你应该会看到一个 pull_request 事件。这表示当你创建拉取请求时，GitHub 成功发送了拉取请求事件。
  3. 在运行npm run server的终端中，你应该会看到类似“Received a pull request event for #1”的信息，其中#后面的整数是你打开的pull request的编号。
  4. 在你的pull request的时间线上，你应该会看到来自你应用的评论。该评论使用了克隆仓库中message.md文件的内容。
  5. 在两个终端窗口中，都输入Ctrl+C来停止你的服务器并停止监听转发的webhooks。

后续步骤

现在你已经有了应用，你可能想扩展应用的代码，部署你的应用，并使你的应用公开。

修改应用代码

Fork github/github-app-js-sample 仓库并修改代码以响应不同的webhook事件或发出不同的API请求。有关代码的更多信息，请参阅“构建响应webhook事件的GitHub App”。

如果你的应用需要你想要发出的API请求或你想要接收的webhook事件的其他权限，请记住更新你的应用的权限。有关更多信息，请参阅“选择GitHub App的权限”。

部署你的应用

本教程使用你的计算机或codespace作为服务器。一旦应用准备好投入生产使用，你应该将你的应用部署到专用服务器。例如，你可以使用Azure App Service。

拥有服务器后，请更新应用设置中的webhook URL。你不应该在生产环境中使用Smee.io来转发你的webhooks。

你还需要更新代码中的port和host常量。有关更多信息，请参阅“构建响应webhook事件的GitHub App”。

你绝不应该公开你的应用的私钥或webhook密钥。本教程将你的应用凭据存储在一个被.gitignore忽略的.env文件中。部署你的应用时，你应该选择一种安全的方式来存储凭据并更新你的代码以相应地获取值。例如，你可以在部署应用的服务器上将凭据存储在环境变量中。你也可以使用密钥管理服务，例如Azure Key Vault。

分享你的应用

如果你想与其他用户和组织共享你的应用，请将你的应用公开。有关更多信息，请参阅“将GitHub App设为公开或私有”。

遵循最佳实践

你应该努力遵循你的GitHub App的最佳实践。有关更多信息，请参阅“创建GitHub App的最佳实践”。