GitHub应用构建快速入门

简介

GitHub Apps 使你能够自动执行进程或将其他平台与 GitHub集成。有关详细信息，请参阅“关于创建GitHub应用”。

本快速入门指南介绍如何快速创建GitHub App。在授予应用访问权限的存储库中打开拉取请求时，应用将向拉取请求添加注释。

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

先决条件

计算机或 codespace 应使用 Node.js 12 及以上的版本。有关详细信息，请参阅 Node.js。

步骤 1：克隆应用代码

为了帮助你快速入门，我们编写了你可以使用的代码。若要了解如何自行编写代码，请参阅“构建响应 Webhook 事件的GitHub应用”。

克隆 github/github-app-js-sample 存储库。有关详细信息，请参阅“克隆仓库”。您可以使用本地克隆或 GitHub Codespaces。
在终端窗口中，导航到存储克隆的目录。
运行 npm install 以安装依赖项。

步骤 2：获取 “Webhook” 代理 URL

若要在本地开发你的应用，可以使用 Webhook 代理 URL 将来自 GitHub 的 Webhook 转发到你的计算机或代码空间。本快速入门使用 Smee.io 提供 Webhook 代理 URL 和转发 Webhook。

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

步骤 3：注册 GitHub App

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

在 GitHub 上任意页的右上角，单击你的个人资料图片。
导航到你的帐户设置。
- 对于由个人帐户拥有的应用，请单击“设置”****。
- 对于组织拥有的应用：
  1. 单击“你的组织”。
  2. 在组织右侧，单击“设置”。
在左边栏中，单击 “Developer settings”****。
在左侧边栏中，单击“GitHub Apps”。
单击“ 新建 GitHub App”。
在“GitHub App 名称”下，输入应用的名称。例如，USERNAME-quickstart-app，其中 USERNAME 是您的 GitHub 用户名。
在“主页 URL”下，输入 https://github.com/github/github-app-js-sample#readme。
跳过本快速入门的“标识和授权用户”和“安装后”部分。有关这些设置的详细信息，请参阅注册GitHub应用。
确保在“Webhook”下选择活动。
在“Webhook URL”下，输入前面提到的 Webhook 代理 URL。有关详细信息，请参阅步骤 2：获取 Webhook 代理 URL。
在“Webhook 机密”下，输入一个随机字符串。稍后会用到此字符串。
在“存储库权限”下的“拉取请求”旁边，选择读取和写入。
在“订阅事件”下面，选择拉取请求。
在“此 GitHub App 可安装在何处？”下，选择 仅在此帐户上。
单击“ 创建 GitHub App”。

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

在本快速入门中，将应用程序的凭据和标识信息作为环境变量存储在 .env 文件中。部署应用时，需要更改凭据的存储方式。有关详细信息，请参阅部署你的应用。

在执行这些步骤之前，请确保你在使用安全的计算机，因为你将在本地存储凭据。

创建 `.env` 文件

克隆的存储库将 .env 包含在 .gitignore 文件中。这可以防止意外提交应用的凭据。有关 .gitignore 文件的详细信息，请参阅“忽略文件”。

导航到存储您的 github/github-app-js-sample 克隆的目录。
在此目录的顶级创建名为 .env 的文件。

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

Text

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

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

导航到应用设置

如果在创建应用后退出了应用设置，请导航到应用的设置页面：

在 GitHub 上任意页的右上角，单击你的个人资料图片。
导航到你的帐户设置。
- 对于由个人帐户拥有的应用，请单击“设置”****。
- 对于组织拥有的应用：
  1. 单击“你的组织”。
  2. 在组织的右侧，单击设置。
在左边栏中，单击 “Developer settings”****。
在左侧边栏中，单击“GitHub Apps”。
在应用名称旁边，单击“编辑”。

获取应用凭据和标识信息

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

步骤 5：安装应用

为了使应用能够对存储库中的拉取请求留下注释，它必须安装在拥有该存储库的帐户上，并获得对该存储库的访问权限。因为应用是私有的，因此只能在拥有该应用的帐户上进行安装。

在拥有所创建应用的帐户中，创建一个新的存储库以安装应用。有关详细信息，请参阅“创建新仓库”。
如果在创建应用后退出了应用设置，请导航到应用的设置页面。有关详细信息，请参阅导航到应用设置。
单击公共页面。
单击“安装” 。
选择“仅选择存储库****”。
选择选择存储库下拉菜单，然后单击在本部分开头选择的存储库。
单击“安装” 。

步骤 6：启动服务器

对于测试，你将使用计算机或 Codespace 作为服务器。应用仅在服务器运行时处于活动状态。

在终端窗口中，导航到存储 github/github-app-js-sample 克隆的目录。
若要从 Smee.io 接收转发的 Webhook，请运行 npx smee -u WEBHOOK_PROXY_URL -t http://localhost:3000/api/webhook。将 WEBHOOK_PROXY_URL 替换为 Webhook 代理 URL。如果忘记了 URL，可以在应用设置页上的“Webhook URL”字段中找到它。

应会看到如下所示的输出，其中 WEBHOOK_PROXY_URL 是 Webhook 代理 URL：
```
Forwarding WEBHOOK_PROXY_URL to http://localhost:3000/api/webhook
Connected WEBHOOK_PROXY_URL
```
在第二个终端窗口中，导航到存储 github/github-app-js-sample 克隆的目录。
运行 npm run server。终端应显示 Server is listening for events at: http://localhost:3000/api/webhook。

步骤 7：测试应用

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

在步骤 5：安装应用中创建的存储库上打开拉取请求。有关详细信息，请参阅“创建拉取请求”。
在 smee.io 上导航到 Webhook 代理 URL。应该会看到 pull_request 事件。这表示 GitHub 在创建拉取请求时已成功发送拉取请求事件。
在运行 npm run server 的终端中，应会看到类似“已收到 #1 的拉取请求事件”的内容，其中 # 后面的整数是打开的拉取请求的编号。
在你的拉取请求的时间线上，你应该会看到来自你的应用的评论。注释使用您克隆的存储库中的message.md文件的内容。
在这两个终端窗口中，输入 Ctrl+C 以停止服务器并停止侦听转发的 Webhook。

后续步骤

有了应用后，你可能想要扩展应用的代码、部署应用并公开应用。

修改应用代码

创建 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 App 有关详细信息，请参阅“创建GitHub应用的最佳做法”。

GitHub应用构建快速入门

在本文中