TaskView集成GitHub与GitLab实战:Issue自动同步为任务,告别手动录入

原创2026-10-12 15:48:541,417 阅读

TaskView集成GitHub与GitLab实战:Issue自动同步为任务,告别手动录入

TaskView 是一款自托管的项目与任务管理平台。本文带你快速完成 TaskView 集成 GitHub 与 GitLab 的配置,通过 OAuth 授权将代码仓库的 Issue 自动同步为 TaskView 任务,并借助 Webhook 实现状态实时双向更新,彻底告别手动录入。

为什么要做 GitHub/GitLab 集成:Issue 与任务双向同步

很多团队的习惯是:Bug 和需求写在 GitHub/GitLab 的 Issue 里,而排期和进度却分散在另一个任务工具中。结果就是同一件事要录入两遍、状态两边不一致。

TaskView 的集成功能直接打通了这两端:

  • 自动同步:授权并选择仓库后,Issue 列表会自动导入为 TaskView 任务,标题、描述、完成状态一一对应
  • 实时推送:集成激活时 TaskView 会在仓库上注册 Webhook,Issue 的 opened / edited / closed / reopened 事件秒级同步
  • 双向更新:在 TaskView 里勾选完成任务,对应的 Issue 会自动关闭;反之在仓库里关闭 Issue,任务也会变为已完成
  • 安全存储:OAuth 令牌使用 AES-256-GCM 加密后落库,GitLab/Gitea 的 refresh token 过期后会自动刷新

相关实现位于 api/src/tv-modules/integrations/IntegrationsManager.ts 与 api/src/tv-modules/integrations/IntegrationsController.ts,同步完成后你的任务列表会呈现如下效果:

TaskView集成GitHub与GitLab后自动同步的Issue任务列表界面

开始集成前,先备好这 3 个条件

按照 docs/3.integrations/1.setup.md 的说明,集成能力需要满足以下前提:

  1. TaskView API 已启动(PostgreSQL 迁移会自动创建 tasks.integrations 与 tasks.integration_task_map 表,无需手工建表)
  2. .env.taskview 中配置了加密密钥 ENCRYPTION_KEY
  3. 在 GitHub / GitLab 侧创建好 OAuth 应用(下面分步讲解)

一键生成加密密钥(ENCRYPTION_KEY)

令牌加密依赖一个 64 位十六进制字符的密钥,用 Node.js 一行命令即可生成:

node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

将输出写入 .env.taskview 的 ENCRYPTION_KEY。⚠️ 注意:密钥一旦更换,已加密的令牌将无法解密,生产环境请妥善保存。

创建 GitHub OAuth App(repo 权限)

  1. 在 GitHub 的 Settings → Developer settings 中新建 OAuth App
  2. Authorization callback URL 填写:http://localhost:1401/module/integrations/oauth/github/callback(生产环境换成你的 API 域名)
  3. 复制 Client ID,并生成 Client Secret

💡 这个 OAuth App 与登录用的 App(GITHUB_CLIENT_ID)是两个独立应用:集成 App 申请 repo 权限,登录 App 只需 user:email。

创建 GitLab OAuth App(api 权限)

  1. 在 GitLab 的 User Settings → Applications 中新建应用
  2. Redirect URI 填写:http://localhost:1401/module/integrations/oauth/gitlab/callback
  3. Scopes 勾选 api
  4. 复制 Application ID 和 Secret

写入 .env.taskview 配置文件

将三组变量加入环境变量(环境变量完整说明见 docs/4.configuration/1.environment-variables.md):

# 集成功能必需
ENCRYPTION_KEY=<你的64位十六进制密钥>

# GitHub 集成 OAuth
GITHUB_INTEGRATION_CLIENT_ID=<your-client-id>
GITHUB_INTEGRATION_CLIENT_SECRET=<your-client-secret>
GITHUB_INTEGRATION_CALLBACK_URL=http://localhost:1401/module/integrations/oauth/github/callback

# GitLab 集成 OAuth
GITLAB_INTEGRATION_CLIENT_ID=<your-application-id>
GITLAB_INTEGRATION_CLIENT_SECRET=<your-secret>
GITLAB_INTEGRATION_CALLBACK_URL=http://localhost:1401/module/integrations/oauth/gitlab/callback

修改完成后重启 API 服务,让新环境变量生效。

四步连接仓库:在 TaskView 界面完成集成

配置完成后,整个连接过程在界面上点几下即可(界面逻辑见 web/src/components/features/integrations/IntegrationsPanel.vue):

  1. 打开目标项目,进入 Integrations 页面
  2. 点击 Add Integration
  3. 选择 GitHub 或 GitLab,浏览器会跳转到对应平台完成 OAuth 授权
  4. 授权成功后回到 TaskView,从仓库列表中选择要同步的仓库

TaskView集成页面选择GitHub或GitLab连接仓库的界面

选择仓库的瞬间,后端会触发两件事:立即执行一次全量 Issue 同步,并自动注册 Webhook(见 IntegrationsManager.ts 中 selectRepo 方法)。之后无需任何人工操作。

Webhook 实时同步:新 Issue 秒变任务

集成激活后,所有后续变更都由 Webhook 驱动,对应仓库 API 端点为 /module/integrations/webhook/github 与 /module/integrations/webhook/gitlab:

仓库侧事件 TaskView 行为
Issue opened 自动创建新任务,描述取自 Issue 正文
Issue edited 同步更新任务标题与备注
Issue closed 任务自动标记完成
Issue reopened 任务重新打开

反向同样成立:你在 TaskView 完成任务,Issue 会自动 close。每个任务还带有指向原始 Issue 的来源链接,点一下即可跳回仓库查看完整讨论。

同步后的项目、列表与任务全景如下:

TaskView项目列表与自动同步的任务看板效果展示

常见问题排查:集成失败的 4 个原因

现象 原因与解决
提示 "GitHub integration OAuth is not configured" .env 缺少 GITHUB_INTEGRATION_CLIENT_ID 或 GITHUB_INTEGRATION_CALLBACK_URL,补齐后重启
提示 "ENCRYPTION_KEY must be a 64-character hex string" 密钥长度不对,用上文命令重新生成
OAuth 回调后跳转到错误地址 检查 APP_URL 是否与前端实际访问地址一致
授权后仓库列表为空 令牌可能过期或集成记录未创建,查看服务端日志后重新授权

生产环境上线前,记得把 Callback URL 换成正式域名,并为生产环境单独创建新的 GitHub/GitLab OAuth App,同时将前端域名加入 CORS_ALLOWED_ORIGINS。

动手之前,看看这些核心文件

至此,TaskView 集成 GitHub 与 GitLab 的完整流程就走完了:生成密钥 → 创建 OAuth App → 配置环境变量 → 界面选择仓库。Issue 从此不再是"第二套台账",而是你任务流的一部分。🚀

登录后查看全文
taskview-community