Kandev集成教程:连接GitHub、GitLab、Jira、Linear、Sentry,把外部Issue拉进看板
Kandev集成教程:连接GitHub、GitLab、Jira、Linear、Sentry,把外部Issue拉进看板
Kandev 是一款自托管的 AI Kanban 开发环境,它内置了 集成(Integrations) 能力:一次连接 GitHub、GitLab、Jira、Linear、Sentry 等外部系统后,你就能在 Kanban 看板里浏览外部 Issue、查看 PR/MR 评审状态,并通过 Watch(监听)机制自动把新 Issue 拉进看板,交给 AI Agent 处理。本教程带你完成完整的 Kandev 集成配置,从零连接到看板自动化。
1️⃣ 先搞懂:3 条互不相通的凭据通道
在动手之前,理解 Kandev 的凭据模型能帮你少踩 80% 的坑。Kandev 里一共有三条独立的认证通道:
| 通道 | 作用 | 配置位置 |
|---|---|---|
| 集成凭据(Integration) | 让 Kandev 后端调用外部平台 API | Settings → Integrations |
| Executor 的 Git/SSH 凭据 | 让任务内的 Agent 拉取和推送代码 | Settings → Executors |
| Agent 登录/API Key | 让编码 CLI 调用模型服务 | Settings → Agents |
⚠️ 关键认知:连通 GitHub 集成 ≠ 任务能 push 代码。三者互不替代,出现"能看不能推"的问题时,请分别排查对应通道。
2️⃣ 打开集成设置页面
配置入口统一位于 Settings → Workspaces → 你的工作区 → Integrations,也可以直接访问快捷路由:
/settings/workspace/{workspaceId}/integrations/github/settings/workspace/{workspaceId}/integrations/gitlab/settings/workspace/{workspaceId}/integrations/jira/settings/workspace/{workspaceId}/integrations/linear/settings/workspace/{workspaceId}/integrations/sentry
两点小提示:
- 配置是工作区级(workspace-specific):配好一个工作区,不代表其他工作区也生效;
- 页面里的 Enabled 开关是"浏览器本地偏好",控制的是入口显示;要真正停止 Watch,必须暂停/删除 Watch 本身。
3️⃣ 连接 GitHub:3 种凭据任选其一
GitHub 是功能最完整的集成,支持 PR、Issue、评审、Checks 浏览与任务联动。在 Workspace automation 卡片中选择连接方式:
| 方式 | 适用场景 | 权限要求 |
|---|---|---|
| Personal access token (PAT) | 个人本地工作区 | Classic 需 repo + read:org;细粒度 Token 按需收窄 |
| GitHub CLI | 后端主机已 gh auth login |
Kandev 只存账号选择,不存 Token |
| GitHub App | 组织级、无人值守自动化 | 推荐;短生命周期安装 Token,密钥服务端保管 |
保存后点击 Test connection 验证。连接成功后访问 /github 即可搜索、浏览 PR 和 Issue,保存常用查询,并直接从结果行 发起一个 Kandev 任务。
关联了 PR 的任务还能启用 Auto-fix CI & address comments(自动修 CI 失败和回复评论)与 Auto-merge or requeue when ready(就绪后自动合并),实现评审闭环自动化。
4️⃣ 连接 GitLab:云版与自建实例都支持
进入 Integrations → GitLab,每个工作区可独立配置一个连接:
- 填写归一化的主机地址(默认
https://gitlab.com,自建实例填完整 HTTPS origin); - 填入 Personal Access Token,需要
api和read_user权限; - Test connection,界面能区分"认证被拒"和"主机不可达"。
连接后可用 /gitlab 浏览 MR 与 Issue、从任务直接 Create Merge Request、在评审面板里回复讨论、Approve、合并。Kandev 还支持 MR Review Watch(监听请求你评审的 MR)与 Issue Watch(监听分配给你的 Issue),轮询间隔默认 300 秒,可调 60–3600 秒。
5️⃣ 连接 Jira:用 JQL 精准筛选 Issue
打开 Integrations → Jira,选择站点类型后填入凭据:
| 部署形态 | 推荐方式 |
|---|---|
| Jira Cloud | API token(Atlassian 账号邮箱 + Token)或 OAuth 2.0 |
| Server/Data Center | Bearer 个人访问令牌 |
连接后访问 /jira:支持 JQL 搜索、保存视图、查看 Issue 详情、执行状态流转,并把 Issue 的标题和描述一键带入新任务。想自动拉 Issue 进看板?创建一个 Issue Watch:
- 默认查询
project = PROJ AND status = "Open" ORDER BY created DESC,替换成你的项目 Key 再测试; - 可选绑定仓库与分支(留空则创建无仓库任务);
- 每次轮询只取前 50 条结果,记得把 JQL 收窄,重要 Issue 才能进第一页。
6️⃣ 连接 Linear:一个 API Key 搞定
Linear 配置最简单:填入 个人 API Key(可选默认 Team),Kandev 会直连官方 GraphQL 端点。保存并测试后,/linear 页面支持按文本、团队、负责人搜索,查看 Issue 详情、变更状态、发起任务。
Linear Watch 的筛选能力非常细:可按 Team、States、Labels、Projects、Priority、Assignee、Creator 组合过滤(至少选一项,条件间为 AND),每个 Project 还能路由到不同仓库——非常适合"一个团队、多个仓库"的场景。
7️⃣ 连接 Sentry:让线上报错自动变成看板任务
Sentry 是唯一支持 多命名实例 的集成(默认 https://sentry.io,也支持自托管)。每个实例填名称、Base URL 和 Bearer Token,需要 org:read、project:read、event:read 三个读权限。
Sentry Watch 默认监听 fatal + error 级别、unresolved 状态 的 Issue,轮询间隔 300 秒。配合指定仓库后,新的线上报错会自动生成一个带上下文的看板任务——错误监控从"被动看"变成"自动修"。
8️⃣ 把 Watch 串起来:外部 Issue 自动流入看板
各家的 Watch 本质都是同一个工作流:轮询外部平台 → 匹配新 Issue/PR/MR → 创建看板任务 → 启动 Agent。以 GitHub 为例:
- Issue Watch:默认查询
type:issue state:open,可选标签或自定义查询; - Review Watch:默认
type:pr state:open review-requested:@me,有人请求你评审就自动开工; - 清理策略三选一:Auto(默认)、Always delete、Never;
- Prompt 支持
{{url}}、{{title}}、issue.*、pr.*等占位符,输入{{可唤起提示。
任务创建后进入正常的工作流泳道,与手动创建的任务完全一致:
9️⃣ 排错指南:最常见的 4 个问题
| 症状 | 排查方向 |
|---|---|
| Test connection 失败 | 核对 Base URL、部署类型、Token 格式与过期时间、网络/DNS |
| 能读不能写 | 只补上需要的写权限 scope,再测一次 |
| 任务无法 push | 这是 Executor 凭据 问题,不是集成问题;GitHub 任务注意检查 GH_TOKEN/GITHUB_TOKEN 覆盖 |
| 关掉 Enabled 后 Watch 还在跑 | Enabled 是本地开关;去暂停/删除 Watch 或移除后端配置 |
另外,GitHub 集成的状态面板还提供 Show GitHub API limits,可查看剩余 API 配额、GraphQL 点数与重置时间,方便判断"PR discovery failed"是否只是被限流。
📚 延伸阅读
- 完整集成文档:docs/public/integrations.md
- 任务与评审流程:docs/public/sessions-and-review.md
- 任务与工作流:docs/public/tasks-and-workflows.md
- 自动化与 MCP:docs/public/automation-and-mcp.md
- Jira 默认视图实现参考:docs/plans/jira-default-view/
连接只需 10 分钟,收益却是长期的:Issue 从外部平台流入看板、Agent 自动认领处理、PR 自动修复与合并——这就是 Kandev 集成体系的完整价值闭环。🚀



