Huly 平台 GitHub 集成本地联调指南：从 GitHub App 注册到 Webhook 同步的完整实战

Huly 平台 GitHub 集成本地联调指南：从 GitHub App 注册到 Webhook 同步的完整实战

【免费下载链接】platformHuly — All-in-One Project Management Platform (alternative to Linear, Jira, Slack, Notion, Motion)项目地址: https://gitcode.com/GitHub_Trending/platform80/platform

本指南以 Huly 平台（All-in-One 项目管理平台）中 GitHub 集成模块（services/github/pod-github，即 GitHub Pod）为对象，系统讲解如何在本地开发环境中从零搭建一套可运行的 GitHub 双向同步能力：包括注册 GitHub App、配置权限与事件订阅、通过 smee 将 GitHub Webhook 转发到本地、以及将应用凭据写入调试配置并完成前端安装联调。阅读本文后，你将掌握 Huly GitHub 集成的整体架构、核心配置项及其在源码中的真实作用，能够独立完成一套可复现的本地测试环境。

一、GitHub Pod 在 Huly 中的作用与整体链路

Huly 的 GitHub 集成并非简单的"登录第三方"，而是一个常驻后台的独立服务（Pod），负责将 GitHub 仓库中的 Issue、Pull Request、Review、Review Comment 等数据与 Huly Tracker 中的任务、讨论进行双向同步。

从仓库结构看，该集成由多个包协作完成：

• services/github/pod-github：集成核心服务（GitHub Pod），处理 GitHub Webhook、OAuth 授权、安装管理，是本文的主角；
• services/github/model-github：数据模型，定义了GithubIntegration、GithubIntegrationRepository、GithubAuthentication、GithubPullRequest、GithubReview、GithubReviewThread、GithubReviewComment等实体；
• services/github/github-resources：前端资源与组件（连接配置、仓库选择、PR 展示等）。

服务启动后，整体链路为：

1. 用户在前端（localhost:8080）发起 GitHub 授权与安装；
2. GitHub 将事件通过 Webhook 推送到 Pod 的/api/webhook端点（本地开发时由 smee 转发）；
3. Pod 通过 Octokit 客户端调用 GitHub REST API 拉取数据，并与 Huly 工作区（workspace）建立长连接；
4. PlatformWorker为每个工作区创建一个GithubWorker，负责具体仓库数据的同步与事件处理。

二、注册一个新的 GitHub App

按照原文档的指引，注册 GitHub App 的入口为 GitHub 的Settings → Developer settings → GitHub Apps，点击New GitHub App创建。

2.1 基本信息配置

其中Callback URL对应前端 OAuth 回调路径，Setup URL携带op=installation参数，用于引导用户完成仓库安装，这两项与后文前端"Settings → Integrations → Github"对话框中的两步操作直接对应。

2.2 配置 Webhook

在创建应用时或创建后进入应用设置页配置 Webhook：

1. 打开 https://smee.io/，点击Start a new channel，创建一个代理通道；
2. 将页面提供的Webhook Proxy URL填入 GitHub App 的Webhook URL（后文简称WEBHOOK_URL）；
3. Webhook secret填写固定值secret；
4. 保持Webhook Active处于勾选状态。

关于secret这个默认值：查看 config.ts 可以发现，Pod 侧WEBHOOK_SECRET环境变量的默认值正是'secret'，即本地开发时 GitHub 侧与 Pod 侧无需额外设置即可互相校验通过。

2.3 配置应用权限

创建 GitHub App 时，需要为其授予以下权限（对应 GitHub App 权限模型 中的定义）：

这些权限覆盖了 GitHub Pod 需要读写的数据范围：Contents用于读取仓库内容与默认分支，Issues与Pull requests用于双向同步任务和 PR，Metadata保持只读以获取仓库与用户元信息，Webhooks用于管理 webhook 配置。

2.4 订阅事件

在Subscribe to events中勾选以下事件：

• Issues
• Pull request
• Pull request review
• Pull request review comment
• Pull request review thread

之所以只订阅这五个事件，可以从 platform.ts 中看到对应关系：pull_request、issues、issue_comment、pull_request_review、pull_request_review_comment、pull_request_review_thread、installation、installation_repositories、projects_v2_item、repository均在 Pod 中有专门的webhooks.on(...)处理器，分别映射到 Huly 侧的GithubPullRequest、tracker.class.Issue、chunter.class.ChatMessage、GithubReview、GithubReviewComment、GithubReviewThread等实体。

2.5 完成创建并获取凭据

创建完成后，按原文档要求收集以下三项关键凭据（后文统一引用其约定代号）：

三、将 Webhook 事件转发到本地（smee）

GitHub 无法直接访问开发者本机的localhost，因此需要借助 smee 这一 Webhook 代理服务把 GitHub 事件中转回本地。

3.1 安装 smee 客户端

npm install --global smee-client

3.2 启动转发

smee -u {WEBHOOK_URL} -t http://localhost:3500/api/webhook

其中：

• {WEBHOOK_URL}是第二步在 smee.io 上创建的 Webhook Proxy URL；
• http://localhost:3500/api/webhook是 Pod 的本地接收端点。端口3500来自 config.ts 中Port环境变量的默认值。

该命令需要保持前台持续运行，GitHub 事件经由WEBHOOK_URL到达 smee 服务器后，会被实时推送至本地 3500 端口的/api/webhook路径。

从源码侧印证接收逻辑：在 server.ts 中，Pod 使用@octokit/webhooks的createNodeMiddleware将/api/webhook挂载到 Express 应用上：

const port = config.Port const path = '/api/webhook' const localWebhookUrl = `http://localhost:${port}${path}` const middleware = createNodeMiddleware(octokitApp.webhooks as any, { path }) const app = express() app.use(middleware as any)

createNodeMiddleware会依据 GitHub 的 webhook 签名与WEBHOOK_SECRET（默认secret）校验请求合法性，再分发给octokitApp.webhooks上的事件处理器。

四、更新本地配置文件

4.1.vscode/launch.json—— "Debug Github integration" 启动配置

在 VS Code 的launch.json中新建/编辑名为Debug Github integration的调试配置，填入以下环境变量：

私钥格式注意事项：原文档特别提示，PRIVATE_KEY的值必须写成单行字符串形式：

"-----BEGIN RSA PRIVATE KEY-----\n {ACTUAL_KEY_WO_LINE_BREAKS}\n-----END RSA PRIVATE KEY-----

即：保留 PEM 头尾标记，中间的密钥内容去掉所有换行，用字面量\n连接。这是因为 config.ts 中会对PRIVATE_KEY环境变量做一次转义还原：

PrivateKey: process.env[envMap.PrivateKey]?.replace(/\\n/g, '\n'),

将字符串中的字面\n替换为真实换行后再交给 Octokit 的App构造器（见 server.ts）用于签发应用令牌。

4.2 前端config.json（dev/prod/public）

在dev/prod/config.json中加入 GitHub 应用信息：

这两项供前端在发起 GitHub OAuth 授权时使用（跳转到https://github.com/login/oauth/authorize时携带client_id）。

五、Pod 核心配置项全览（源码级解读）

config.ts 定义了 GitHub Pod 的全部环境变量，下表为完整配置清单，含默认值与必填性：

关键参数的作用机理：

• PRIVATE_KEY与APP_ID一起构造 Octokit 的App实例（server.ts），App负责为每个安装签发 installation token；
• WEBHOOK_SECRET用于createNodeMiddleware的签名校验，两端不一致会导致事件被拒；
• RATE_LIMIT在 platform.ts 中被封装为TimeRateLimiter，按 GitHub API 端点（endpoint）分别限流，避免触发 GitHub 的 API 速率限制；
• WORKSPACE_INACTIVITY_INTERVAL控制空闲工作区是否停止同步：checkReconnect与checkWorkspaces会根据WorkspaceInfoWithStatus中的lastVisit判断，若超过该天数则关闭对应GithubWorker（见 platform.ts 与 platform.ts）；
• ALLOWED_WORKSPACES支持*通配，表示允许所有工作区接入。

本地一键启动脚本见 run.sh，其内容可作为本地运行时的环境变量参考：

export APP_ID="$POD_GITHUB_APPID" export CLIENT_ID="$POD_GITHUB_CLIENTID" export CLIENT_SECRET="$POD_GITHUB_CLIENT_SECRET" export PRIVATE_KEY="$POD_GITHUB_PRIVATE_KEY" export SERVER_SECRET=secret export ACCOUNTS_URL=http://localhost:3000 export COLLABORATOR_URL=ws://huly.local:3078 export STORAGE_CONFIG="datalake|http://huly.local:4030" rush bundle --to @hcengineering/pod-github node $@ bundle/bundle.js $@

注意：这里PRIVATE_KEY直接以 shell 变量传入，实际取值仍遵循"单行\n拼接"的格式约定。生产部署时，Pod 提供了 Dockerfile，基于hardcoreeng/base-slim镜像运行打包后的bundle.js。

六、运行与前端联调

6.1 启动步骤

1. 在 VS Code 中以Debug Github integration配置启动 GitHub Pod（对应services/github/pod-github）；
2. 启动 Huly 前端 dev server（默认localhost:8080）；
3. 保持 smee 转发命令持续运行。

Pod 启动后会在控制台输出监听地址，例如：

Server is listening for events at: http://localhost:3500/api/webhook

6.2 前端安装与连接

在浏览器打开http://localhost:8080，进入Settings → Integrations → Github，在弹窗中完成两步操作：

1. 第一个标签页：点击授权（Authorise），完成 GitHub OAuth 登录授权；
2. 第二个标签页：安装（Install）应用，选择一个 GitHub 仓库，然后在 Huly Tracker 中连接到一个已存在的仓库或创建一个新的关联仓库（connected repo）。

授权成功后，Pod 会通过POST /api/v1/auth端点（见 server.ts）用 OAuthcode换取用户访问令牌，并将用户的 GitHub 登录名、头像等信息写入工作区的GithubAuthentication记录；安装完成后，Pod 会通过POST /api/v1/installation（server.ts）建立 workspace ↔ installation 的映射，随后开始仓库数据同步。

6.3 常见问题与提示

• 应用已被安装但数据未同步：原文档给出的处理办法是，在 GitHub App 安装设置中任意改动一下（例如在 "All repositories" 与 "Only select repositories" 之间切换），然后点击Save，即可触发installation_repositories/installation事件，Pod 会重新加载仓库列表并触发同步。
• 授权状态异常（Bad credentials）：从源码看，若用户令牌失效，Pod 会捕获err.response?.data?.message === 'Bad credentials'并自动撤销该用户的认证记录（见 platform.ts），此时需要重新走一遍授权流程。
• 令牌过期：GitHub 用户令牌（access token）有时效，Pod 内置了 refresh token 刷新逻辑checkRefreshToken（platform.ts），刷新失败时会撤销认证。
• 一个安装被迁移到其他工作区：mapInstallation处理了同一 installation 从旧工作区迁移到新工作区的场景，会移除旧工作区中的集成记录并重新同步（platform.ts）。

七、延伸阅读

• 本文主题文档原文：services/github/pod-github/Readme.md
• Webhook 接收与 REST 端点：services/github/pod-github/src/server.ts
• 环境变量与配置解析：services/github/pod-github/src/config.ts
• 安装管理与事件分发：services/github/pod-github/src/platform.ts
• 数据模型定义：services/github/model-github/src/index.ts
• 本地运行脚本与容器镜像：services/github/pod-github/run.sh、services/github/pod-github/Dockerfile
• 前端集成组件（仓库选择、连接配置、PR 展示等）：services/github/github-resources/src/components

按照上述步骤完成配置后，你就拥有了一套完整的 Huly ↔ GitHub 本地联调环境：GitHub 上的 Issue、PR、Review 及其评论都会实时同步到 Huly Tracker，反之亦然。如需在生产环境使用，只需将localhost相关地址替换为实际域名，并将 Webhook URL 指向真实部署的 Pod 端点即可。

【免费下载链接】platformHuly — All-in-One Project Management Platform (alternative to Linear, Jira, Slack, Notion, Motion)项目地址: https://gitcode.com/GitHub_Trending/platform80/platform