# GitHub应用构建快速入门

快速构建一个对拉取请求发表评论的 GitHub App。

## 简介

GitHub Apps 使你能够自动执行进程或将其他平台与 GitHub集成。 有关详细信息，请参阅“[关于创建GitHub应用](/zh/enterprise-server@3.22/apps/creating-github-apps/about-creating-github-apps/about-creating-github-apps)”。

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

本快速入门使用预先编写的代码来帮助你快速入门。 有关有助于你编写代码的更详细教程，请参阅“[构建响应 Webhook 事件的GitHub应用](/zh/enterprise-server@3.22/apps/creating-github-apps/writing-code-for-a-github-app/building-a-github-app-that-responds-to-webhook-events)”。

## 先决条件

计算机或 codespace 应使用 Node.js 12 及以上的版本。 有关详细信息，请参阅 [Node.js](https://nodejs.org)。

## 步骤 1：克隆应用代码

为了帮助你快速入门，我们编写了你可以使用的代码。 若要了解如何自行编写代码，请参阅“[构建响应 Webhook 事件的GitHub应用](/zh/enterprise-server@3.22/apps/creating-github-apps/writing-code-for-a-github-app/building-a-github-app-that-responds-to-webhook-events)”。

1. 克隆 [github/github-app-js-sample](https://github.com/github/github-app-js-sample) 存储库。 有关详细信息，请参阅“[克隆仓库](/zh/enterprise-server@3.22/repositories/creating-and-managing-repositories/cloning-a-repository)”。 您可以使用本地克隆或 GitHub Codespaces。
2. 在终端窗口中，导航到存储克隆的目录。
3. 运行 `npm install` 以安装依赖项。

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

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

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

## 步骤 3：注册 GitHub App

以下步骤将指导你配置本快速入门所需的应用设置。 有关这些设置的详细信息，请参阅“[注册GitHub应用](/zh/enterprise-server@3.22/apps/creating-github-apps/registering-a-github-app/registering-a-github-app)”。

1. 在 GitHub 上任意页的右上角，单击你的个人资料图片。
2. 导航到你的帐户设置。
   * 对于由个人帐户拥有的应用，请单击“设置”\*\*\*\*。
   * 对于组织拥有的应用：
     1. 单击“你的组织”。
     2. 在组织右侧，单击“设置”。
3. 在左边栏中，单击 <svg version="1.1" width="16" height="16" viewBox="0 0 16 16" class="octicon octicon-code" aria-label="code" role="img"><path d="m11.28 3.22 4.25 4.25a.75.75 0 0 1 0 1.06l-4.25 4.25a.749.749 0 0 1-1.275-.326.749.749 0 0 1 .215-.734L13.94 8l-3.72-3.72a.749.749 0 0 1 .326-1.275.749.749 0 0 1 .734.215Zm-6.56 0a.751.751 0 0 1 1.042.018.751.751 0 0 1 .018 1.042L2.06 8l3.72 3.72a.749.749 0 0 1-.326 1.275.749.749 0 0 1-.734-.215L.47 8.53a.75.75 0 0 1 0-1.06Z"></path></svg>“Developer settings”\*\*\*\*。
4. 在左侧边栏中，单击“GitHub Apps”。
5. 单击“ **新建 GitHub App**”。
6. 在“GitHub App 名称”下，输入应用的名称。 例如，`USERNAME-quickstart-app`，其中 `USERNAME` 是您的 GitHub 用户名。
7. 在“主页 URL”下，输入 `https://github.com/github/github-app-js-sample#readme`。
8. 跳过本快速入门的“标识和授权用户”和“安装后”部分。 有关这些设置的详细信息，请参阅 [注册GitHub应用](/zh/enterprise-server@3.22/apps/creating-github-apps/registering-a-github-app/registering-a-github-app)。
9. 确保在“Webhook”下选择**活动**。
10. 在“Webhook URL”下，输入前面提到的 Webhook 代理 URL。 有关详细信息，请参阅[步骤 2：获取 Webhook 代理 URL](#step-2-get-a-webhook-proxy-url)。
11. 在“Webhook 机密”下，输入一个随机字符串。 稍后会用到此字符串。
12. 在“存储库权限”下的“拉取请求”旁边，选择**读取和写入**。
13. 在“订阅事件”下面，选择**拉取请求**。
14. 在“此 GitHub App 可安装在何处？”下，选择 **仅在此帐户上**。
15. 单击“ **创建 GitHub App**”。

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

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

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

### 创建 `.env` 文件

克隆的存储库将 `.env` 包含在 `.gitignore` 文件中。 这可以防止意外提交应用的凭据。 有关 `.gitignore` 文件的详细信息，请参阅“[忽略文件](/zh/enterprise-server@3.22/get-started/git-basics/ignoring-files)”。

1. 导航到存储您的 [github/github-app-js-sample](https://github.com/github/github-app-js-sample) 克隆的目录。
2. 在此目录的顶级创建名为 `.env` 的文件。
3. 将以下内容添加到 `.env` 文件。 用的名称替换`YOUR_HOSTNAME`。 将在后面的步骤中更新其他值。

   ```text copy
   APP_ID="YOUR_APP_ID"
   WEBHOOK_SECRET="YOUR_WEBHOOK_SECRET"
   PRIVATE_KEY_PATH="YOUR_PRIVATE_KEY_PATH"
   HOSTNAME="YOUR_HOSTNAME"
   ```

### 导航到应用设置

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

1. 在 GitHub 上任意页的右上角，单击你的个人资料图片。

2. 导航到你的帐户设置。
   * 对于由个人帐户拥有的应用，请单击“设置”\*\*\*\*。
   * 对于组织拥有的应用：
     1. 单击“你的组织”。
     2. 在组织的右侧，单击**设置**。
   * 对于由企业拥有的应用：
     1. 单击**企业设置**。

3. 在左边栏中，单击 <svg version="1.1" width="16" height="16" viewBox="0 0 16 16" class="octicon octicon-code" aria-label="code" role="img"><path d="m11.28 3.22 4.25 4.25a.75.75 0 0 1 0 1.06l-4.25 4.25a.749.749 0 0 1-1.275-.326.749.749 0 0 1 .215-.734L13.94 8l-3.72-3.72a.749.749 0 0 1 .326-1.275.749.749 0 0 1 .734.215Zm-6.56 0a.751.751 0 0 1 1.042.018.751.751 0 0 1 .018 1.042L2.06 8l3.72 3.72a.749.749 0 0 1-.326 1.275.749.749 0 0 1-.734-.215L.47 8.53a.75.75 0 0 1 0-1.06Z"></path></svg>“Developer settings”\*\*\*\*。

4. 在左侧边栏中，单击“GitHub Apps”。

5. 在应用名称旁边，单击“编辑”。

### 获取应用凭据和标识信息

1. 在应用的设置页上，在“应用 ID”旁边，找到应用的应用 ID。
2. 在 `.env` 文件中，将 `YOUR_APP_ID` 替换为应用的应用 ID。
3. 在应用的设置页上，在“私钥”下，单击**生成私钥**。 您将看到一个以 PEM 格式下载至您的计算机的私钥。 有关详细信息，请参阅“[管理GitHub应用的私钥](/zh/enterprise-server@3.22/apps/creating-github-apps/authenticating-with-a-github-app/managing-private-keys-for-github-apps)”。
4. 如果使用的是 codespace，请将下载的 PEM 文件移到 codespace 中，以便 codespace 可以访问该文件。
5. 在 `.env` 文件中，将 `YOUR_PRIVATE_KEY_PATH` 替换为私钥的完整路径，包括 `.pem` 扩展名。
6. 在 `.env` 文件中，将 `YOUR_WEBHOOK_SECRET` 替换为应用的 Webhook 机密。 如果忘记了 Webhook 机密，请在“Webhook 机密（可选）”下面单击**更改机密**。 输入新机密，然后单击**保存更改**。

## 步骤 5：安装应用

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

1. 在拥有所创建应用的帐户中，创建一个新的存储库以安装应用。 有关详细信息，请参阅“[创建新仓库](/zh/enterprise-server@3.22/repositories/creating-and-managing-repositories/creating-a-new-repository)”。
2. 如果在创建应用后退出了应用设置，请导航到应用的设置页面。 有关详细信息，请参阅[导航到应用设置](#navigate-to-your-app-settings)。
3. 单击**公共页面**。
4. 单击“安装” 。
5. 选择“仅选择存储库\*\*\*\*”。
6. 选择**选择存储库**下拉菜单，然后单击在本部分开头选择的存储库。
7. 单击“安装” 。

## 步骤 6：启动服务器

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

1. 在终端窗口中，导航到存储 [github/github-app-js-sample](https://github.com/github/github-app-js-sample) 克隆的目录。

2. 若要从 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：

   ```shell
   Forwarding WEBHOOK_PROXY_URL to http://localhost:3000/api/webhook
   Connected WEBHOOK_PROXY_URL
   ```

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

4. 运行 `npm run server`。 终端应显示 `Server is listening for events at: http://localhost:3000/api/webhook`。

## 步骤 7：测试应用

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

1. 在[步骤 5：安装应用](#step-5-install-your-app)中创建的存储库上打开拉取请求。 有关详细信息，请参阅“[创建拉取请求](/zh/enterprise-server@3.22/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request)”。
2. 在 smee.io 上导航到 Webhook 代理 URL。 应该会看到 `pull_request` 事件。 这表示 GitHub 在创建拉取请求时已成功发送拉取请求事件。
3. 在运行 `npm run server` 的终端中，应会看到类似“已收到 #1 的拉取请求事件”的内容，其中 `#` 后面的整数是打开的拉取请求的编号。
4. 在你的拉取请求的时间线上，你应该会看到来自你的应用的评论。 注释使用您克隆的存储库中的`message.md`文件的内容。
5. 在这两个终端窗口中，输入 <kbd>Ctrl</kbd>+<kbd>C</kbd> 以停止服务器并停止侦听转发的 Webhook。

## 后续步骤

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

### 修改应用代码

创建 [github/github-app-js-sample](https://github.com/github/github-app-js-sample) 存储库的分支，并修改代码以响应不同的 Webhook 事件或发出不同的 API 请求。 有关代码的详细信息，请参阅“[构建响应 Webhook 事件的GitHub应用](/zh/enterprise-server@3.22/apps/creating-github-apps/writing-code-for-a-github-app/building-a-github-app-that-responds-to-webhook-events)”。

针对你要发出的 API 请求或希望接收的 Webhook 事件，如果应用需要其他权限，请记得更新应用的权限。 有关详细信息，请参阅“[为GitHub应用选择权限](/zh/enterprise-server@3.22/apps/creating-github-apps/registering-a-github-app/choosing-permissions-for-a-github-app)”。

### 部署你的应用

本教程将您的计算机或代码空间作为服务器使用。 应用可供生产使用后，应将应用部署到专用服务器。 例如，可以使用 [Azure 应用服务](https://azure.microsoft.com/products/app-service/)。

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

还需要更新代码中的 `port` 和 `host` 常量。 有关详细信息，请参阅“[构建响应 Webhook 事件的GitHub应用](/zh/enterprise-server@3.22/apps/creating-github-apps/writing-code-for-a-github-app/building-a-github-app-that-responds-to-webhook-events#deploy-your-app)”。

切勿公开应用的私钥或 Webhook 机密。 本教程将应用的凭据存储在 gitignored `.env` 文件中。 部署应用时，应选择一种安全的方式来存储凭据并更新代码以获取相应值。 例如，可以将凭据存储在部署应用的服务器上的环境变量中。 还可以使用机密管理服务，例如 [Azure 密钥保管库](https://azure.microsoft.com/en-us/products/key-vault)。

### 共享应用

如果要与其他用户和组织共享应用，请公开应用。 有关详细信息，请参阅“[将GitHub应用公开或专用](/zh/enterprise-server@3.22/apps/creating-github-apps/registering-a-github-app/making-a-github-app-public-or-private)”。

### 遵循最佳做法

应努力遵循最佳做法。GitHub App 有关详细信息，请参阅“[创建GitHub应用的最佳做法](/zh/enterprise-server@3.22/apps/creating-github-apps/about-creating-github-apps/best-practices-for-creating-a-github-app)”。