有关生成 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 将 Webhook 从 GitHub 转发到你的计算机或 codespace。本快速入门使用 Smee.io 提供 Webhook 代理 URL 和转发 Webhook。

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

步骤 3：注册 GitHub App

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

在 GitHub 上任意页的右上角，单击你的个人资料照片。
导航到你的帐户设置。
- 对于由个人帐户拥有的应用，请单击“设置”****。
- 对于组织拥有的应用：
  1. 单击“你的组织”。
  2. 在组织右侧，单击“设置”。
在左侧边栏中，单击“ 开发人员设置”。
在左侧边栏中，单击“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 文件。将 YOUR_HOSTNAME 替换为你的 GitHub Enterprise Server 实例的名称。将在后面的步骤中更新其他值。

Text

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

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

导航到应用设置

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

在 GitHub 上任意页的右上角，单击你的个人资料照片。
导航到你的帐户设置。
- 对于由个人帐户拥有的应用，请单击“设置”****。
- 对于组织拥有的应用：
  1. 单击“你的组织”。
  2. 在组织的右侧，单击设置。
在左侧边栏中，单击“ 开发人员设置”。
在左侧边栏中，单击“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 Apps 选择权限”。

部署你的应用

本教程使用了计算机或 codespace 作为服务器。应用可供生产使用后，应将应用部署到专用服务器。例如，可以使用 Azure 应用服务。

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

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

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

如果要与其他用户和组织共享应用，请公开应用。有关详细信息，请参阅“将 GitHub 应用程序设为公共或私有”。

遵循最佳做法

你的目标应该是遵循 GitHub App 的最佳做法。有关详细信息，请参阅“创建 GitHub 应用的最佳做法”。

本文内容