目标:将 OpenCode 与代码托管平台深度集成
概述
OpenCode 原生支持 GitHub 和 GitLab 工作流,配合 MCP 服务器可以实现从 Issue 查看到 PR 创建的全流程自动化。本章覆盖配置方法、实战场景和标准化工作流。
Git 工作流 Mermaid 图
完整开发工作流
AI 辅助代码审查流程
GitHub 集成
内置 GitHub 支持
OpenCode 原生支持 GitHub 工作流:
- 查看 Issue 和 PR
- 创建 PR
- 代码审查
- 搜索仓库
配置方式
方式一:交互式配置
/connect
选择 GitHub,按提示授权。
方式二:MCP 配置(推荐团队)
{
"mcp": {
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
}
}
}
}方式三:环境变量
export GITHUB_TOKEN=ghp_xxxxxxxxxxxxPR 创建完整示例
场景:基于功能分支创建 PR
步骤 1:确认当前分支和变更
# 查看当前分支
git branch --show-current
# feature/user-auth
# 查看变更
git diff --stat main步骤 2:使用 OpenCode 创建 PR
基于当前分支创建一个 PR,标题是"添加用户认证功能",描述包含:
1. 实现了 JWT 登录/注册
2. 添加了密码哈希
3. 关联 Issue #15
OpenCode 会执行(通过 MCP):
// 内部调用的 GitHub API 等价操作
{
"title": "添加用户认证功能",
"body": "## 变更内容\n\n1. 实现了 JWT 登录/注册\n2. 添加了 bcrypt 密码哈希(cost: 12)\n3. 统一错误处理格式\n\n## 关联 Issue\n\nCloses #15",
"head": "feature/user-auth",
"base": "main"
}步骤 3:验证 PR 创建成功
查看我刚才创建的 PR 的详情
真实场景案例 ①:标准化 PR 流程
某团队要求所有 PR 必须包含"变更内容、测试说明、关联 Issue"三部分。开发者将这一要求写入 OpenCode 规则:
{ "rules": [ "创建 PR 时,描述必须包含:变更内容、测试说明、关联 Issue" ] }AI 自动生成符合规范的 PR 描述,审查者不再需要反复要求补充信息。
PR 描述模板(AI 自动生成示例)
## 变更内容
- ✅ 实现用户登录 API (`POST /api/auth/login`)
- ✅ 实现用户注册 API (`POST /api/auth/register`)
- ✅ 添加 JWT token 生成与验证中间件
- ✅ 密码使用 bcrypt 哈希存储
## 测试说明
- [x] 登录成功/失败场景单元测试
- [x] 注册字段校验测试
- [x] JWT 中间件测试
## 关联 Issue
Closes #15代码审查流程
AI 辅助审查命令
审查 @src/auth.ts 的修改,指出潜在问题
审查检查清单
# AI 代码审查报告
## 🔴 严重
- [ ] SQL 注入风险
- [ ] 硬编码密钥
- [ ] 未处理敏感数据
## 🟡 警告
- [ ] 错误处理不完整
- [ ] 性能问题(N+1 查询等)
- [ ] 边界情况未覆盖
## 🟢 建议
- [ ] 命名优化
- [ ] 注释补充
- [ ] 代码简化审查示例输出
🤖 审查结果:
🔴 严重(1)
位置: src/auth.ts:42
问题: 密码使用 md5 哈希,不安全
建议: 改用 bcrypt,cost factor ≥ 12
🟡 警告(2)
位置: src/auth.ts:28
问题: JWT secret 从环境变量读取,但未验证是否存在
建议: 启动时检查 process.env.JWT_SECRET,不存在则抛错
位置: src/auth.ts:55
问题: 登录失败返回 200,应返回 401
建议: 统一使用 401 Unauthorized
🟢 建议(1)
位置: src/auth.ts:15
建议: 提取验证逻辑到单独的 validateLoginInput 函数
真实场景案例 ②:AI 审查发现安全漏洞
某开发者在实现文件上传功能时,AI 审查发现未限制文件类型和大小,可能导致任意文件上传漏洞。开发者根据建议添加了白名单校验和大小限制,避免了潜在的安全事故。
Issue 处理模板
查看 Issue
查看 Issue #23 的详情和讨论
分析 Issue 并制定计划
分析 Issue #23,制定修复计划并列出需要修改的文件
AI 输出示例:
## Issue #23 分析
**问题**: 用户报告登录后 token 很快过期
**根因分析**:
1. JWT 过期时间设置为 15 分钟
2. 没有实现 refresh token 机制
**修复计划**:
1. [ ] 修改 `src/config/auth.ts`,将 access token 过期时间改为 15 分钟
2. [ ] 创建 `src/services/refreshToken.ts`,实现 refresh token 生成与验证
3. [ ] 修改 `src/routes/auth.ts`,添加 `/auth/refresh` 端点
4. [ ] 修改前端拦截器,自动刷新 token
**预计影响文件**:
- src/config/auth.ts
- src/services/refreshToken.ts
- src/routes/auth.ts
- src/middleware/auth.tsIssue 关联与自动关闭
创建 PR 时自动关联 Issue:
{
"rules": [
"创建 PR 时,如果修复了 Issue,在描述中添加 'Closes #N' 或 'Fixes #N'"
]
}真实场景案例 ③:Sprint 自动化
某敏捷团队将 OpenCode 与 GitHub Projects 结合。Sprint 开始时,开发者让 AI 分析分配的 Issue,自动生成任务拆分和文件修改清单。Sprint 结束时,AI 汇总所有 PR,生成 Sprint 总结报告。
GitLab 集成
配置方式与 GitHub 类似:
/connect
选择 GitLab,输入实例 URL 和 Token。
GitLab CI 集成
# .gitlab-ci.yml
ai-code-review:
stage: test
image: node:20
script:
- npm install -g opencode
- export OPENCODE_CONFIG_CONTENT='{"permission":{"edit":"deny","bash":"deny"}}'
- opencode review --diff $CI_MERGE_REQUEST_DIFF_BASE_SHA
only:
- merge_requests工作流示例
场景:修复 Bug 并提交 PR
1. 查看 Issue #15 的描述
2. 分析问题原因
3. 修复代码
4. 运行测试
5. 创建 PR 关联 Issue #15
OpenCode 可以辅助完成大部分步骤。
完整会话示例
> 查看 Issue #15
🤖 Issue #15: 登录接口返回 500 错误
标签: bug, backend
描述: 当密码为空字符串时,服务器返回 500 而非 400...
> 分析原因并定位问题文件
🤖 分析中...
可能原因: `src/auth.ts:23` 未校验空密码直接传入 bcrypt.compare
相关文件: src/auth.ts, src/validators/auth.ts
> 帮我修复这个问题,添加输入校验
🤖 已修改 src/auth.ts 和 src/validators/auth.ts
- 添加 z.object({ email, password: z.string().min(6) }) 校验
- 空密码现在返回 400 Bad Request
> 运行测试
🤖 运行 npm test...
✓ auth.test.ts (5/5 passed)
> 基于当前分支创建 PR,关联 Issue #15
🤖 PR #47 已创建: "修复空密码导致的 500 错误"
关联: Closes #15
FAQ
Q: GitHub Token 需要什么权限?
A: 至少需要
repo(私有仓库)或public_repo(公开仓库)。如需操作 Issue,额外需要issues权限。
Q: 可以在 CI 中自动运行 AI 审查吗?
A: 可以。配置 GitHub Actions 或 GitLab CI,在 PR 创建时触发 OpenCode 进行代码审查,结果作为评论发布到 PR。
Q: AI 创建的 PR 需要人工确认吗?
A: 强烈建议人工确认。AI 可以辅助生成 PR 内容,但最终提交应由开发者审核。
Q: GitLab 自托管实例能用吗?
A: 可以。在
/connect或配置中指定自托管 GitLab 的 URL 和 Personal Access Token。
避坑清单 ⚠️
| 坑 | 后果 | 正确做法 |
|---|---|---|
| 将 GitHub Token 写入配置文件 | Token 泄露,仓库被恶意操作 | 使用环境变量或密钥管理服务 |
| AI 自动创建 PR 后不检查 | 代码质量问题流入主分支 | 始终人工审查 AI 生成的 PR |
| 忽略 AI 的审查警告 | 安全漏洞或性能问题被合并 | 认真对待每条 🔴 严重级别警告 |
| PR 描述过于简单 | 审查者无法理解变更意图 | 使用模板,包含变更/测试/关联 Issue |
| 在公共仓库使用高权限 Token | 第三方可获取 Token | 为不同仓库创建细粒度 Token |
| 合并前不运行 CI | 破坏主分支 | 强制要求 CI 通过才能合并 |
练习
- 配置 GitHub MCP,查看一个你参与的仓库的 Issue 列表
- 让 AI 审查你最近的一次代码提交
- 创建一个带有完整描述的 PR(使用 AI 辅助)
- 设置一个 Issue 处理到 PR 合并的完整工作流
下一篇:14. Web 界面与 IDE