{"meta":{"title":"GitHub应用构建快速入门","intro":"快速构建一个对拉取请求发表评论的 GitHub App。","product":"应用","breadcrumbs":[{"href":"/zh/apps","title":"应用"},{"href":"/zh/apps/creating-github-apps","title":"创建GitHub应用"},{"href":"/zh/apps/creating-github-apps/writing-code-for-a-github-app","title":"为GitHub应用编写代码"},{"href":"/zh/apps/creating-github-apps/writing-code-for-a-github-app/quickstart","title":"快速入门"}],"documentType":"article"},"body":"# GitHub应用构建快速入门\n\n快速构建一个对拉取请求发表评论的 GitHub App。\n\n## 简介\n\nGitHub Apps 使你能够自动执行进程或将其他平台与 GitHub集成。 有关详细信息，请参阅“[关于创建GitHub应用](/zh/apps/creating-github-apps/about-creating-github-apps/about-creating-github-apps)”。\n\n本快速入门指南介绍如何快速创建GitHub App。 在授予应用访问权限的存储库中打开拉取请求时，应用将向拉取请求添加注释。\n\n本快速入门使用预先编写的代码来帮助你快速入门。 有关有助于你编写代码的更详细教程，请参阅“[构建响应 Webhook 事件的GitHub应用](/zh/apps/creating-github-apps/writing-code-for-a-github-app/building-a-github-app-that-responds-to-webhook-events)”。\n\n## 先决条件\n\n计算机或 codespace 应使用 Node.js 12 及以上的版本。 有关详细信息，请参阅 [Node.js](https://nodejs.org)。\n\n## 步骤 1：克隆应用代码\n\n为了帮助你快速入门，我们编写了你可以使用的代码。 若要了解如何自行编写代码，请参阅“[构建响应 Webhook 事件的GitHub应用](/zh/apps/creating-github-apps/writing-code-for-a-github-app/building-a-github-app-that-responds-to-webhook-events)”。\n\n1. 克隆 [github/github-app-js-sample](https://github.com/github/github-app-js-sample) 存储库。 有关详细信息，请参阅“[克隆仓库](/zh/repositories/creating-and-managing-repositories/cloning-a-repository)”。 您可以使用本地克隆或 GitHub Codespaces。\n2. 在终端窗口中，导航到存储克隆的目录。\n3. 运行 `npm install` 以安装依赖项。\n\n## 步骤 2：获取 “Webhook” 代理 URL\n\n若要在本地开发你的应用，可以使用 Webhook 代理 URL 将来自 GitHub 的 Webhook 转发到你的计算机或代码空间。 本快速入门使用 Smee.io 提供 Webhook 代理 URL 和转发 Webhook。\n\n1. 在浏览器中，导航到  <https://smee.io/> 。\n2. 单击**启动新频道**。\n3. 复制“Webhook 代理 URL”下的完整 URL。 你将在后面的步骤中使用此 URL。\n\n## 步骤 3：注册 GitHub App\n\n以下步骤将指导你配置本快速入门所需的应用设置。 有关这些设置的详细信息，请参阅“[注册GitHub应用](/zh/apps/creating-github-apps/registering-a-github-app/registering-a-github-app)”。\n\n1. 在 GitHub 上任意页的右上角，单击你的个人资料图片。\n2. 导航到你的帐户设置。\n   * 对于由个人帐户拥有的应用，请单击“设置”\\*\\*\\*\\*。\n   * 对于组织拥有的应用：\n     1. 单击“你的组织”。\n     2. 在组织右侧，单击“设置”。\n3. 在左边栏中，单击 <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”\\*\\*\\*\\*。\n4. 在左侧边栏中，单击“GitHub Apps”。\n5. 单击“ **新建 GitHub App**”。\n6. 在“GitHub App 名称”下，输入应用的名称。 例如，`USERNAME-quickstart-app`，其中 `USERNAME` 是您的 GitHub 用户名。\n7. 在“主页 URL”下，输入 `https://github.com/github/github-app-js-sample#readme`。\n8. 跳过本快速入门的“标识和授权用户”和“安装后”部分。 有关这些设置的详细信息，请参阅 [注册GitHub应用](/zh/apps/creating-github-apps/registering-a-github-app/registering-a-github-app)。\n9. 确保在“Webhook”下选择**活动**。\n10. 在“Webhook URL”下，输入前面提到的 Webhook 代理 URL。 有关详细信息，请参阅[步骤 2：获取 Webhook 代理 URL](#step-2-get-a-webhook-proxy-url)。\n11. 在“Webhook 机密”下，输入一个随机字符串。 稍后会用到此字符串。\n12. 在“存储库权限”下的“拉取请求”旁边，选择**读取和写入**。\n13. 在“订阅事件”下面，选择**拉取请求**。\n14. 在“此 GitHub App 可安装在何处？”下，选择 **仅在此帐户上**。\n15. 单击“ **创建 GitHub App**”。\n\n## 步骤 4：存储标识信息和凭据\n\n在本快速入门中，将应用程序的凭据和标识信息作为环境变量存储在 `.env` 文件中。 部署应用时，需要更改凭据的存储方式。 有关详细信息，请参阅[部署你的应用](#deploy-your-app)。\n\n在执行这些步骤之前，请确保你在使用安全的计算机，因为你将在本地存储凭据。\n\n### 创建 `.env` 文件\n\n克隆的存储库将 `.env` 包含在 `.gitignore` 文件中。 这可以防止意外提交应用的凭据。 有关 `.gitignore` 文件的详细信息，请参阅“[忽略文件](/zh/get-started/git-basics/ignoring-files)”。\n\n1. 导航到存储您的 [github/github-app-js-sample](https://github.com/github/github-app-js-sample) 克隆的目录。\n2. 在此目录的顶级创建名为 `.env` 的文件。\n3. 将以下内容添加到 `.env` 文件。 用将在后面的步骤中更新这些值。\n\n   ```text copy\n   APP_ID=\"YOUR_APP_ID\"\n   WEBHOOK_SECRET=\"YOUR_WEBHOOK_SECRET\"\n   PRIVATE_KEY_PATH=\"YOUR_PRIVATE_KEY_PATH\"\n   ```\n\n### 导航到应用设置\n\n如果在创建应用后退出了应用设置，请导航到应用的设置页面：\n\n1. 在 GitHub 上任意页的右上角，单击你的个人资料图片。\n2. 导航到你的帐户设置。\n   * 对于由个人帐户拥有的应用，请单击“设置”\\*\\*\\*\\*。\n   * 对于组织拥有的应用：\n     1. 单击“你的组织”。\n     2. 在组织的右侧，单击**设置**。\n3. 在左边栏中，单击 <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”\\*\\*\\*\\*。\n4. 在左侧边栏中，单击“GitHub Apps”。\n5. 在应用名称旁边，单击“编辑”。\n\n### 获取应用凭据和标识信息\n\n1. 在应用的设置页上，在“应用 ID”旁边，找到应用的应用 ID。\n2. 在 `.env` 文件中，将 `YOUR_APP_ID` 替换为应用的应用 ID。\n3. 在应用的设置页上，在“私钥”下，单击**生成私钥**。 您将看到一个以 PEM 格式下载至您的计算机的私钥。 有关详细信息，请参阅“[管理GitHub应用的私钥](/zh/apps/creating-github-apps/authenticating-with-a-github-app/managing-private-keys-for-github-apps)”。\n4. 如果使用的是 codespace，请将下载的 PEM 文件移到 codespace 中，以便 codespace 可以访问该文件。\n5. 在 `.env` 文件中，将 `YOUR_PRIVATE_KEY_PATH` 替换为私钥的完整路径，包括 `.pem` 扩展名。\n6. 在 `.env` 文件中，将 `YOUR_WEBHOOK_SECRET` 替换为应用的 Webhook 机密。 如果忘记了 Webhook 机密，请在“Webhook 机密（可选）”下面单击**更改机密**。 输入新机密，然后单击**保存更改**。\n\n## 步骤 5：安装应用\n\n为了使应用能够对存储库中的拉取请求留下注释，它必须安装在拥有该存储库的帐户上，并获得对该存储库的访问权限。 因为应用是私有的，因此只能在拥有该应用的帐户上进行安装。\n\n1. 在拥有所创建应用的帐户中，创建一个新的存储库以安装应用。 有关详细信息，请参阅“[创建新仓库](/zh/repositories/creating-and-managing-repositories/creating-a-new-repository)”。\n2. 如果在创建应用后退出了应用设置，请导航到应用的设置页面。 有关详细信息，请参阅[导航到应用设置](#navigate-to-your-app-settings)。\n3. 单击**公共页面**。\n4. 单击“安装” 。\n5. 选择“仅选择存储库\\*\\*\\*\\*”。\n6. 选择**选择存储库**下拉菜单，然后单击在本部分开头选择的存储库。\n7. 单击“安装” 。\n\n## 步骤 6：启动服务器\n\n对于测试，你将使用计算机或 Codespace 作为服务器。 应用仅在服务器运行时处于活动状态。\n\n1. 在终端窗口中，导航到存储 [github/github-app-js-sample](https://github.com/github/github-app-js-sample) 克隆的目录。\n\n2. 若要从 Smee.io 接收转发的 Webhook，请运行 `npx smee -u WEBHOOK_PROXY_URL -t http://localhost:3000/api/webhook`。 将 `WEBHOOK_PROXY_URL` 替换为 Webhook 代理 URL。 如果忘记了 URL，可以在应用设置页上的“Webhook URL”字段中找到它。\n\n   应会看到如下所示的输出，其中 `WEBHOOK_PROXY_URL` 是 Webhook 代理 URL：\n\n   ```shell\n   Forwarding WEBHOOK_PROXY_URL to http://localhost:3000/api/webhook\n   Connected WEBHOOK_PROXY_URL\n   ```\n\n3. 在第二个终端窗口中，导航到存储 [github/github-app-js-sample](https://github.com/github/github-app-js-sample) 克隆的目录。\n\n4. 运行 `npm run server`。 终端应显示 `Server is listening for events at: http://localhost:3000/api/webhook`。\n\n## 步骤 7：测试应用\n\n现在，服务器已运行并接收转发的 Webhook 事件，请通过打开一个拉取请求来测试应用。\n\n1. 在[步骤 5：安装应用](#step-5-install-your-app)中创建的存储库上打开拉取请求。 有关详细信息，请参阅“[创建拉取请求](/zh/pull-requests/how-tos/create-pull-requests/creating-a-pull-request)”。\n2. 在 smee.io 上导航到 Webhook 代理 URL。 应该会看到 `pull_request` 事件。 这表示 GitHub 在创建拉取请求时已成功发送拉取请求事件。\n3. 在运行 `npm run server` 的终端中，应会看到类似“已收到 #1 的拉取请求事件”的内容，其中 `#` 后面的整数是打开的拉取请求的编号。\n4. 在你的拉取请求的时间线上，你应该会看到来自你的应用的评论。 注释使用您克隆的存储库中的`message.md`文件的内容。\n5. 在这两个终端窗口中，输入 <kbd>Ctrl</kbd>+<kbd>C</kbd> 以停止服务器并停止侦听转发的 Webhook。\n\n## 后续步骤\n\n有了应用后，你可能想要扩展应用的代码、部署应用并公开应用。\n\n### 修改应用代码\n\n创建 [github/github-app-js-sample](https://github.com/github/github-app-js-sample) 存储库的分支，并修改代码以响应不同的 Webhook 事件或发出不同的 API 请求。 有关代码的详细信息，请参阅“[构建响应 Webhook 事件的GitHub应用](/zh/apps/creating-github-apps/writing-code-for-a-github-app/building-a-github-app-that-responds-to-webhook-events)”。\n\n针对你要发出的 API 请求或希望接收的 Webhook 事件，如果应用需要其他权限，请记得更新应用的权限。 有关详细信息，请参阅“[为GitHub应用选择权限](/zh/apps/creating-github-apps/registering-a-github-app/choosing-permissions-for-a-github-app)”。\n\n### 部署你的应用\n\n本教程将您的计算机或代码空间作为服务器使用。 应用可供生产使用后，应将应用部署到专用服务器。 例如，可以使用 [Azure 应用服务](https://azure.microsoft.com/products/app-service/)。\n\n有了服务器后，请在应用设置中更新 Webhook URL。 不应使用 Smee.io 在生产环境中转发 Webhook。\n\n还需要更新代码中的 `port` 和 `host` 常量。 有关详细信息，请参阅“[构建响应 Webhook 事件的GitHub应用](/zh/apps/creating-github-apps/writing-code-for-a-github-app/building-a-github-app-that-responds-to-webhook-events#deploy-your-app)”。\n\n切勿公开应用的私钥或 Webhook 机密。 本教程将应用的凭据存储在 gitignored `.env` 文件中。 部署应用时，应选择一种安全的方式来存储凭据并更新代码以获取相应值。 例如，可以将凭据存储在部署应用的服务器上的环境变量中。 还可以使用机密管理服务，例如 [Azure 密钥保管库](https://azure.microsoft.com/en-us/products/key-vault)。\n\n### 共享应用\n\n如果要与其他用户和组织共享应用，请公开应用。 有关详细信息，请参阅“[将GitHub应用公开或专用](/zh/apps/creating-github-apps/registering-a-github-app/making-a-github-app-public-or-private)”。\n\n### 遵循最佳做法\n\n应努力遵循最佳做法。GitHub App 有关详细信息，请参阅“[创建GitHub应用的最佳做法](/zh/apps/creating-github-apps/about-creating-github-apps/best-practices-for-creating-a-github-app)”。"}