构建 GitHub 应用程序的快速入门

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

本文内容

简介

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

本快速入门介绍如何快速创建 GitHub 应用程序。当在应用程序被授予访问权限的存储库中打开拉取请求时，应用程序将向拉取请求添加评论。

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

先决条件

您的计算机或代码空间应使用 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 转发到您的计算机或代码空间。此快速入门使用 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 Apps**。
  5. 点击 **New GitHub App**。
  6. 在“GitHub App name”下，输入您的应用名称。例如，USERNAME-quickstart-app，其中 USERNAME 是您的 GitHub 用户名。
  7. 在“Homepage URL”下，输入 https://github.com/github/github-app-js-sample#readme。
  8. 跳过“Identifying and authorizing users”和“Post installation”部分，本快速入门不需要这些设置。有关这些设置的更多信息，请参阅“注册 GitHub 应用”。
  9. 确保在“Webhooks”下选择了 **Active**。
  10. 在“Webhook URL”下，输入您之前获得的 webhook 代理 URL。有关更多信息，请参阅“步骤 2：获取 webhook 代理 URL”。
  11. 在“Webhook secret”下，输入一个随机字符串。您将在稍后使用此字符串。
  12. 在“Repository permissions”下，在“Pull requests”旁边，选择 **Read & write**。
  13. 在“Subscribe to events”下，选择 **Pull request**。
  14. 在“Where can this GitHub App be installed?”下，选择 **Only on this account**。
  15. 点击 **Create GitHub App**。

步骤 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 Apps**。
  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”的内容，其中#后面的整数是您打开的拉取请求的编号。
  4. 在您的拉取请求的时间轴中，您应该看到来自您的应用的评论。该评论使用您克隆的仓库中message.md文件的内容。
  5. 在两个终端窗口中，输入Ctrl+C以停止您的服务器并停止监听转发后的Webhook。

下一步

现在您有了应用，您可能想要扩展您的应用代码、部署您的应用并使您的应用公开。

修改应用代码

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

请记住，如果您的应用需要您想要进行的API请求或您想要接收的Webhook事件的额外权限，请更新您的应用权限。有关更多信息，请参阅“为GitHub应用选择权限”。

部署您的应用

本教程使用您的计算机或代码空间作为服务器。当应用程序准备好投入生产使用时，您应该将应用程序部署到专用服务器。例如，您可以使用 Azure 应用服务。

拥有服务器后，请在应用程序设置中更新 Webhook URL。在生产环境中，您不应使用 Smee.io 来转发您的 Webhook。

您还需要更新代码中的 port 和 host 常量。有关更多信息，请参阅 "构建响应 Webhook 事件的 GitHub 应用程序。"。

您永远不应该公开应用程序的私钥或 Webhook 密钥。本教程将应用程序的凭据存储在 gitignored .env 文件中。部署应用程序时，您应该选择一种安全的方式来存储凭据，并更新代码以相应地获取值。例如，您可以在应用程序部署的服务器上将凭据存储在环境变量中。您还可以使用秘密管理服务，例如 Azure 密钥保管库。

分享您的应用程序

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

遵循最佳实践

您应该努力遵循 GitHub 应用程序的最佳实践。有关更多信息，请参阅 "创建 GitHub 应用程序的最佳实践。"。