| name | gitcode-merge-flow |
| description | Automates GitCode open-source repo merge workflow: commit → push → issue → PR → pipeline → review → /lgtm & /approve → merge. Invoke when user wants to submit code to a GitCode open-source repository. |
GitCode 开源仓合入流程自动化
自动化完成从本地提交到代码合入开源仓的完整流程。当需要向 GitCode 开源仓库贡献代码时调用此 Skill。
配置要求
执行前必须确认以下配置：
- GITCODE_ACCESS_TOKEN: GitCode API 访问令牌，从项目根目录的
token 文件读取，或由用户提供
- 个人仓: 用户 fork 的个人仓库（格式：
owner/repo，如 skywang2/skill-test）
- 开源仓: 上游开源仓库（格式：
owner/repo，如 lyzin/111）
- GITCODE_API_BASE: API 基础地址，默认
https://api.gitcode.com/api/v5
完整流程
flowchart TD
A["本地提交"] --> B["远程推送"]
B --> C["提交Issue"]
C --> D["提交PR"]
D --> E["触发流水线"]
E --> F{"存在流水线失败问题?"}
F -->|是| G["解决流水线失败问题"]
G --> E
F -->|否| H["等待代码评审"]
H --> I{"存在未解决评审意见?"}
I -->|是| J["解决评审意见"]
J --> H
I -->|否| K{"存在新提交解决的评审意见?"}
K -->|是| E
K -->|否| L["等待/lgtm和/approve"]
L --> M["确认合入"]
执行步骤
步骤1: 前置检查
- 读取项目根目录
token 文件获取 GITCODE_ACCESS_TOKEN，若不存在则向用户索取
- 确认当前工作目录是一个 git 仓库（检查
.git 目录是否存在）
- 向用户确认以下信息（若未提供则询问）：
- 个人仓 (
owner/repo 格式): 如 skywang2/skill-test
- 开源仓 (
owner/repo 格式): 如 lyzin/111
- 目标分支: 默认
master
- 当前工作分支: 默认当前 git 分支名
- Issue 标题和描述（参考
references/issue-templates.md 中的模板）
- PR 标题
- PR 描述（参考
references/pr-template.md 中的模板）
步骤2: 本地提交
- 运行
git status 检查是否有未暂存的更改
- 如果有更改：
- 运行
git add -A 暂存所有更改（或按用户指定文件）
- 运行
git commit -m "<commit_message>" 提交，commit_message 由用户提供或根据更改自动生成
- 如果没有更改，提示用户确认是否继续
步骤3: 远程推送
- 确认个人仓远程已配置：
git remote -v
- 如果没有个人仓远程，添加：
git remote add origin https://gitcode.com/<personal_owner>/<personal_repo>.git
- 推送到个人仓：
git push origin <current_branch>
- 如果推送失败（如远程拒绝），处理冲突后重试
步骤4: 提交 Issue
调用 GitCode API 在开源仓创建 Issue。
API 详情：请参考 references/api.md 中的「创建 Issue」部分。
执行脚本：使用 scripts/create_issue.py 脚本。
记录返回的 Issue 编号（number 字段），后续创建 PR 时关联。
步骤5: 提交 PR
调用 GitCode API 从个人仓向开源仓创建 PR。
API 详情：请参考 references/api.md 中的「创建 PR」部分。
执行脚本：使用 scripts/create_pr.py 脚本。
【重要】提交数限制：
- 如果当前分支的提交数大于 1，必须使用 squash 合并
- 在创建 PR 前检查本地提交数量：
git log --oneline origin/main..main
- 若提交数 > 1，提示用户需要 squash 或 rebase 后再创建 PR
记录返回的 PR 编号（number 字段），后续步骤均依赖此编号。
步骤5.5: 关联 PR 和 Issue（可选）
如果需要显式关联 PR 和 Issue，可以调用关联 API。
API 详情：请参考 references/api.md 中的「关联 PR 和 Issue」部分。
执行脚本：使用 scripts/link_pr_issue.py 脚本。
注意：此操作需要仓库维护者权限，普通贡献者可能无法执行。创建 PR 时设置 close_related_issue: true 可以自动关联 Issue。
步骤6: 检查流水线状态
PR 创建后流水线会自动触发。获取流水线状态并直接挂起，让用户自行确认。
API 详情：请参考 references/api.md 中的「获取 PR 详情」部分。
执行脚本：使用 scripts/get_pr_details.py 脚本（字段 mergeable_state.ci_state_passed）。
【挂起反馈示例 - 步骤6】：
⏸️ 流程已挂起 - 请确认流水线状态
📋 当前状态：
• PR 链接: https://gitcode.com/{owner}/{repo}/merge_requests/{number}
• 流水线状态: ✅ 通过 / ❌ 失败 / ⏳ 运行中
• 合并状态: ✅ 可合并 / ❌ 不可合并
⏳ 请确认：
请在 PR 页面确认流水线是否通过
流水线通过后请告知我继续流程
若流水线失败，请在修复后告知我
📝 流水线失败处理：
1. 修复代码问题
2. 执行 git add → git commit → git push 推送新提交
3. 新提交会自动重新触发流水线
4. 流水线通过后告知我继续
步骤7: 等待代码评审
【强制要求】无论仓库配置如何，必须等待至少一个维护者进行代码评审通过后方可继续。
获取 PR 的评审评论并检查评审状态。
API 详情：请参考 references/api.md 中的「获取 PR 评论」部分。
执行脚本：使用 scripts/get_pr_comments.py 脚本。
评审状态判断逻辑：
- 如果没有任何评审评论 → 尚未有人评审，强制挂起流程
- 如果存在
resolved: false 的评论 → 有未解决的评审意见
- 如果所有评论
resolved: true → 评审意见已全部解决
【挂起反馈示例 - 步骤7】：
当流程因等待评审而挂起时，必须向用户清晰展示：
⏸️ 流程已挂起 - 等待代码评审
📋 当前状态：
• PR 链接: https://gitcode.com/{owner}/{repo}/merge_requests/{number}
• 流水线状态: ✅ 通过
• 评审状态: ❌ 暂无评审评论 / ⚠️ 有未解决评审意见
⏳ 等待操作：
需要至少一个维护者进行代码评审
📝 下一步：
请联系仓库维护者进行评审
评审完成后请告知我，我将检查评审状态并继续流程
存在未解决评审意见：
- 列出所有未解决的评审意见（评论内容和作者）
- 强制挂起流程
- 用户修改代码后，执行
git add → git commit → git push 推送新提交
- 新提交推送后，告知我重新检查
步骤8: 等待 /lgtm 和 /approve
【强制要求】无论仓库配置如何，必须获得至少一个 /lgtm 或 /approve 评论表态后方可合入。
检查 PR 评论，确认是否有人通过评论 /lgtm 或 /approve 表示同意合入。
执行脚本：使用 scripts/get_pr_comments.py 脚本。
判断逻辑：
- 如果未找到
/lgtm 或 /approve → 挂起流程
- 如果找到
/lgtm 或 /approve → 进入步骤9
【挂起反馈示例 - 步骤8】：
⏸️ 流程已挂起 - 等待 /lgtm 和 /approve 审批
📋 当前状态：
• PR 链接: https://gitcode.com/{owner}/{repo}/merge_requests/{number}
• 流水线状态: ✅ 通过
• 评审状态: ✅ 已通过
• 审批状态: ❌ 暂无 /lgtm 或 /approve
⏳ 等待操作：
需要仓库维护者通过评论 /lgtm 或 /approve 表示同意合入
📝 下一步：
请仓库维护者在 PR 页面评论 /lgtm 或 /approve
获得审批后请告知我，我将执行合并
步骤10: 确认合入
所有条件满足后，调用 API 合入 PR。
API 详情：请参考 references/api.md 中的「合并 PR」部分。
执行脚本：使用 scripts/merge_pr.py 脚本。
【重要】合并方式：
- 提交数大于 1 时，必须使用 squash 合并
merge_pr.py 脚本会自动检查 PR 的提交数量，若大于 1 则强制使用 squash- 提交数 = 1 时，可使用 merge 或 squash（默认 squash）
合入成功后：
- 告知用户 PR 已成功合入
- 提供合入后的 PR 链接
- 建议用户同步本地主分支：
git pull upstream master
挂起与恢复机制
流程中以下步骤需要等待第三方人工操作，会直接挂起：
| 挂起点 | 等待原因 | 恢复条件 |
|---|
| 步骤6: 流水线检查 | 需要用户确认流水线状态 | 用户确认流水线通过后告知我继续 |
| 步骤7: 等待评审 | 需要评审人审查代码 | 用户确认评审完成后告知我继续 |
| 步骤8: 等待 /lgtm 和 /approve | 需要维护者审批 | 用户确认已获得审批后告知我继续 |
挂起时的行为：
- 明确告知用户当前挂起的原因
- 告知用户需要等待什么操作
- 提供相关链接（PR 页面、流水线页面等）
- 用户确认后，从挂起点继续执行
错误处理
- API 调用失败：检查 access_token 是否有效，网络是否通畅，参数是否正确
- Git 操作失败：检查远程仓库权限、分支是否存在、是否有冲突
- PR 已关闭/拒绝：告知用户 PR 状态，询问是否重新提交
- 合并冲突：提示用户解决冲突后重新推送
注意事项
- 所有 API 调用使用 Python 的
requests 库
- access_token 不得硬编码在代码中，必须从 token 文件读取或由用户输入
- 推送代码时如需认证，使用 URL 嵌入 token 的方式：
https://oauth2:<token>@gitcode.com/<owner>/<repo>.git
- 创建 PR 时
head 参数必须包含个人仓 owner 前缀，格式为 <owner>:<branch>
- 轮询流水线状态时注意频率控制，避免触发 API 限流
- 需要安装依赖：
pip install requests
