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 展示等。服务启动后整体链路为用户在前端localhost:8080发起 GitHub 授权与安装GitHub 将事件通过 Webhook 推送到 Pod 的/api/webhook端点本地开发时由 smee 转发Pod 通过 Octokit 客户端调用 GitHub REST API 拉取数据并与 Huly 工作区workspace建立长连接PlatformWorker为每个工作区创建一个GithubWorker负责具体仓库数据的同步与事件处理。二、注册一个新的 GitHub App按照原文档的指引注册 GitHub App 的入口为 GitHub 的Settings → Developer settings → GitHub Apps点击New GitHub App创建。2.1 基本信息配置配置项取值说明Name任意唯一名称例如XX_huly_dev后文统一称为GITHUB_APPHomepage URLhttp://localhost:8080对应本地前端地址Callback URLhttp://localhost:8080/githubOAuth 授权回调地址Setup URL可选http://localhost:8080/github?opinstallation安装引导页Redirect on update勾选应用信息更新后自动跳转其中Callback URL对应前端 OAuth 回调路径Setup URL携带opinstallation参数用于引导用户完成仓库安装这两项与后文前端Settings → Integrations → Github对话框中的两步操作直接对应。2.2 配置 Webhook在创建应用时或创建后进入应用设置页配置 Webhook打开 https://smee.io/点击Start a new channel创建一个代理通道将页面提供的Webhook Proxy URL填入 GitHub App 的Webhook URL后文简称WEBHOOK_URLWebhook secret填写固定值secret保持Webhook Active处于勾选状态。关于secret这个默认值查看 config.ts 可以发现Pod 侧WEBHOOK_SECRET环境变量的默认值正是secret即本地开发时 GitHub 侧与 Pod 侧无需额外设置即可互相校验通过。2.3 配置应用权限创建 GitHub App 时需要为其授予以下权限对应 GitHub App 权限模型 中的定义权限级别Commit statusesRead and writeContentsRead and writeCustom propertiesRead and writeDiscussionsRead and writeIssuesRead and writeMetadataRead-onlyPagesRead and writeProjectsRead and writePull requestsRead and writeWebhooksRead and write这些权限覆盖了 GitHub Pod 需要读写的数据范围Contents用于读取仓库内容与默认分支Issues与Pull requests用于双向同步任务和 PRMetadata保持只读以获取仓库与用户元信息Webhooks用于管理 webhook 配置。2.4 订阅事件在Subscribe to events中勾选以下事件IssuesPull requestPull request reviewPull request review commentPull 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 完成创建并获取凭据创建完成后按原文档要求收集以下三项关键凭据后文统一引用其约定代号代号来源用途POD_GITHUB_CLIENT_SECRET点击Generate a new client secret生成用于 OAuth 换取用户访问令牌POD_GITHUB_PRIVATE_KEY创建并下载的私钥文件用于以 GitHub App 身份签发 JWT、调用 APIPOD_GITHUB_APPID应用页面提供的 App ID数字形式的应用唯一标识三、将 Webhook 事件转发到本地smeeGitHub 无法直接访问开发者本机的localhost因此需要借助 smee 这一 Webhook 代理服务把 GitHub 事件中转回本地。3.1 安装 smee 客户端npm install --global smee-client3.2 启动转发smee -u {WEBHOOK_URL} -t http://localhost:3500/api/webhook其中{WEBHOOK_URL}是第二步在 smee.io 上创建的 Webhook Proxy URLhttp://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的调试配置填入以下环境变量键值APP_ID{POD_GITHUB_APPID}新建应用的数字 App IDCLIENT_ID{POD_GITHUB_CLIENTID}应用的 Client IDCLIENT_SECRET{POD_GITHUB_CLIENT_SECRET}应用的 Client SecretPRIVATE_KEY{POD_GITHUB_PRIVATE_KEY}应用的私钥私钥格式注意事项原文档特别提示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.jsondev/prod/public在dev/prod/config.json中加入 GitHub 应用信息键值GITHUB_APP{GITHUB_APP}应用文本名称如XX_huly_devGITHUB_CLIENTID{POD_GITHUB_CLIENTID}应用的 Client ID这两项供前端在发起 GitHub OAuth 授权时使用跳转到https://github.com/login/oauth/authorize时携带client_id。五、Pod 核心配置项全览源码级解读config.ts 定义了 GitHub Pod 的全部环境变量下表为完整配置清单含默认值与必填性环境变量配置含义默认值是否必填ACCOUNTS_URLAccount 服务地址用于获取集成记录与工作区信息—是SERVER_SECRET服务间通信令牌密钥server-token的 Secret—是SERVICE_ID服务标识github-service否FRONT_URL前端地址空字符串是APP_IDGitHub App ID数字—是CLIENT_IDGitHub App Client ID—是CLIENT_SECRETGitHub App Client Secret—是PRIVATE_KEYGitHub App 私钥单行\n格式—是WEBHOOK_SECRETWebhook 校验密钥secret否ENTERPRISE_HOSTNAMEGitHub Enterprise 主机名自建 GHE 场景未设置否PORT本地 HTTP 监听端口3500否ALLOWED_WORKSPACES允许同步的工作区列表逗号分隔*全部否BOT_NAME机器人账号名用于提交评论/PR 操作ao-huly-dev[bot]否COLLABORATOR_URL协作文档服务地址WebSocket—是BRANDING_PATH品牌配置路径空字符串否WORKSPACE_INACTIVITY_INTERVAL工作区停止同步前的空闲天数3天否RATE_LIMIT每个端点每秒最大操作数限流25否关键参数的作用机理PRIVATE_KEY与APP_ID一起构造 Octokit 的App实例server.tsApp负责为每个安装签发 installation tokenWEBHOOK_SECRET用于createNodeMiddleware的签名校验两端不一致会导致事件被拒RATE_LIMIT在 platform.ts 中被封装为TimeRateLimiter按 GitHub API 端点endpoint分别限流避免触发 GitHub 的 API 速率限制WORKSPACE_INACTIVITY_INTERVAL控制空闲工作区是否停止同步checkReconnect与checkWorkspaces会根据WorkspaceInfoWithStatus中的lastVisit判断若超过该天数则关闭对应GithubWorker见 platform.ts 与 platform.tsALLOWED_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_SECRETsecret export ACCOUNTS_URLhttp://localhost:3000 export COLLABORATOR_URLws://huly.local:3078 export STORAGE_CONFIGdatalake|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 启动步骤在 VS Code 中以Debug Github integration配置启动 GitHub Pod对应services/github/pod-github启动 Huly 前端 dev server默认localhost:8080保持 smee 转发命令持续运行。Pod 启动后会在控制台输出监听地址例如Server is listening for events at: http://localhost:3500/api/webhook6.2 前端安装与连接在浏览器打开http://localhost:8080进入Settings → Integrations → Github在弹窗中完成两步操作第一个标签页点击授权Authorise完成 GitHub OAuth 登录授权第二个标签页安装Install应用选择一个 GitHub 仓库然后在 Huly Tracker 中连接到一个已存在的仓库或创建一个新的关联仓库connected repo。授权成功后Pod 会通过POST /api/v1/auth端点见 server.ts用 OAuthcode换取用户访问令牌并将用户的 GitHub 登录名、头像等信息写入工作区的GithubAuthentication记录安装完成后Pod 会通过POST /api/v1/installationserver.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 刷新逻辑checkRefreshTokenplatform.ts刷新失败时会撤销认证。一个安装被迁移到其他工作区mapInstallation处理了同一 installation 从旧工作区迁移到新工作区的场景会移除旧工作区中的集成记录并重新同步platform.ts。七、延伸阅读本文主题文档原文services/github/pod-github/Readme.mdWebhook 接收与 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
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 展示等。服务启动后整体链路为用户在前端localhost:8080发起 GitHub 授权与安装GitHub 将事件通过 Webhook 推送到 Pod 的/api/webhook端点本地开发时由 smee 转发Pod 通过 Octokit 客户端调用 GitHub REST API 拉取数据并与 Huly 工作区workspace建立长连接PlatformWorker为每个工作区创建一个GithubWorker负责具体仓库数据的同步与事件处理。二、注册一个新的 GitHub App按照原文档的指引注册 GitHub App 的入口为 GitHub 的Settings → Developer settings → GitHub Apps点击New GitHub App创建。2.1 基本信息配置配置项取值说明Name任意唯一名称例如XX_huly_dev后文统一称为GITHUB_APPHomepage URLhttp://localhost:8080对应本地前端地址Callback URLhttp://localhost:8080/githubOAuth 授权回调地址Setup URL可选http://localhost:8080/github?opinstallation安装引导页Redirect on update勾选应用信息更新后自动跳转其中Callback URL对应前端 OAuth 回调路径Setup URL携带opinstallation参数用于引导用户完成仓库安装这两项与后文前端Settings → Integrations → Github对话框中的两步操作直接对应。2.2 配置 Webhook在创建应用时或创建后进入应用设置页配置 Webhook打开 https://smee.io/点击Start a new channel创建一个代理通道将页面提供的Webhook Proxy URL填入 GitHub App 的Webhook URL后文简称WEBHOOK_URLWebhook secret填写固定值secret保持Webhook Active处于勾选状态。关于secret这个默认值查看 config.ts 可以发现Pod 侧WEBHOOK_SECRET环境变量的默认值正是secret即本地开发时 GitHub 侧与 Pod 侧无需额外设置即可互相校验通过。2.3 配置应用权限创建 GitHub App 时需要为其授予以下权限对应 GitHub App 权限模型 中的定义权限级别Commit statusesRead and writeContentsRead and writeCustom propertiesRead and writeDiscussionsRead and writeIssuesRead and writeMetadataRead-onlyPagesRead and writeProjectsRead and writePull requestsRead and writeWebhooksRead and write这些权限覆盖了 GitHub Pod 需要读写的数据范围Contents用于读取仓库内容与默认分支Issues与Pull requests用于双向同步任务和 PRMetadata保持只读以获取仓库与用户元信息Webhooks用于管理 webhook 配置。2.4 订阅事件在Subscribe to events中勾选以下事件IssuesPull requestPull request reviewPull request review commentPull 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 完成创建并获取凭据创建完成后按原文档要求收集以下三项关键凭据后文统一引用其约定代号代号来源用途POD_GITHUB_CLIENT_SECRET点击Generate a new client secret生成用于 OAuth 换取用户访问令牌POD_GITHUB_PRIVATE_KEY创建并下载的私钥文件用于以 GitHub App 身份签发 JWT、调用 APIPOD_GITHUB_APPID应用页面提供的 App ID数字形式的应用唯一标识三、将 Webhook 事件转发到本地smeeGitHub 无法直接访问开发者本机的localhost因此需要借助 smee 这一 Webhook 代理服务把 GitHub 事件中转回本地。3.1 安装 smee 客户端npm install --global smee-client3.2 启动转发smee -u {WEBHOOK_URL} -t http://localhost:3500/api/webhook其中{WEBHOOK_URL}是第二步在 smee.io 上创建的 Webhook Proxy URLhttp://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的调试配置填入以下环境变量键值APP_ID{POD_GITHUB_APPID}新建应用的数字 App IDCLIENT_ID{POD_GITHUB_CLIENTID}应用的 Client IDCLIENT_SECRET{POD_GITHUB_CLIENT_SECRET}应用的 Client SecretPRIVATE_KEY{POD_GITHUB_PRIVATE_KEY}应用的私钥私钥格式注意事项原文档特别提示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.jsondev/prod/public在dev/prod/config.json中加入 GitHub 应用信息键值GITHUB_APP{GITHUB_APP}应用文本名称如XX_huly_devGITHUB_CLIENTID{POD_GITHUB_CLIENTID}应用的 Client ID这两项供前端在发起 GitHub OAuth 授权时使用跳转到https://github.com/login/oauth/authorize时携带client_id。五、Pod 核心配置项全览源码级解读config.ts 定义了 GitHub Pod 的全部环境变量下表为完整配置清单含默认值与必填性环境变量配置含义默认值是否必填ACCOUNTS_URLAccount 服务地址用于获取集成记录与工作区信息—是SERVER_SECRET服务间通信令牌密钥server-token的 Secret—是SERVICE_ID服务标识github-service否FRONT_URL前端地址空字符串是APP_IDGitHub App ID数字—是CLIENT_IDGitHub App Client ID—是CLIENT_SECRETGitHub App Client Secret—是PRIVATE_KEYGitHub App 私钥单行\n格式—是WEBHOOK_SECRETWebhook 校验密钥secret否ENTERPRISE_HOSTNAMEGitHub Enterprise 主机名自建 GHE 场景未设置否PORT本地 HTTP 监听端口3500否ALLOWED_WORKSPACES允许同步的工作区列表逗号分隔*全部否BOT_NAME机器人账号名用于提交评论/PR 操作ao-huly-dev[bot]否COLLABORATOR_URL协作文档服务地址WebSocket—是BRANDING_PATH品牌配置路径空字符串否WORKSPACE_INACTIVITY_INTERVAL工作区停止同步前的空闲天数3天否RATE_LIMIT每个端点每秒最大操作数限流25否关键参数的作用机理PRIVATE_KEY与APP_ID一起构造 Octokit 的App实例server.tsApp负责为每个安装签发 installation tokenWEBHOOK_SECRET用于createNodeMiddleware的签名校验两端不一致会导致事件被拒RATE_LIMIT在 platform.ts 中被封装为TimeRateLimiter按 GitHub API 端点endpoint分别限流避免触发 GitHub 的 API 速率限制WORKSPACE_INACTIVITY_INTERVAL控制空闲工作区是否停止同步checkReconnect与checkWorkspaces会根据WorkspaceInfoWithStatus中的lastVisit判断若超过该天数则关闭对应GithubWorker见 platform.ts 与 platform.tsALLOWED_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_SECRETsecret export ACCOUNTS_URLhttp://localhost:3000 export COLLABORATOR_URLws://huly.local:3078 export STORAGE_CONFIGdatalake|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 启动步骤在 VS Code 中以Debug Github integration配置启动 GitHub Pod对应services/github/pod-github启动 Huly 前端 dev server默认localhost:8080保持 smee 转发命令持续运行。Pod 启动后会在控制台输出监听地址例如Server is listening for events at: http://localhost:3500/api/webhook6.2 前端安装与连接在浏览器打开http://localhost:8080进入Settings → Integrations → Github在弹窗中完成两步操作第一个标签页点击授权Authorise完成 GitHub OAuth 登录授权第二个标签页安装Install应用选择一个 GitHub 仓库然后在 Huly Tracker 中连接到一个已存在的仓库或创建一个新的关联仓库connected repo。授权成功后Pod 会通过POST /api/v1/auth端点见 server.ts用 OAuthcode换取用户访问令牌并将用户的 GitHub 登录名、头像等信息写入工作区的GithubAuthentication记录安装完成后Pod 会通过POST /api/v1/installationserver.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 刷新逻辑checkRefreshTokenplatform.ts刷新失败时会撤销认证。一个安装被迁移到其他工作区mapInstallation处理了同一 installation 从旧工作区迁移到新工作区的场景会移除旧工作区中的集成记录并重新同步platform.ts。七、延伸阅读本文主题文档原文services/github/pod-github/Readme.mdWebhook 接收与 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
技术解析与实践指南)
