gitlink-cli/skills/gitlink-workflow/REFERENCE.md

gitlink-workflow 参考手册

本文档定义跨模块工作流的 API 字段映射、Fork 协作流程和分支命名规范。

---

一、跨模块 API 字段关联

核心关联关系

repo +info
├── project_id ──────────────────→ milestone +list (project_id)
├── forked_from_project_id ──────→ upstream 仓库标识
├── open_devops ─────────────────→ ci +builds 可用性
└── default_branch ──────────────→ branch +protect 的目标

pr +create
├── --head <user>:<branch> ──────→ branch +create 的产物
├── --base <branch> ─────────────→ 目标分支（通常 master）
└── pr +view 返回的 id ──────────→ pr +merge / pr +files 的参数

issue +create
└── 返回的 project_issues_index ──→ issue +close / issue +comment 的 --number

PR 状态映射

pull_request_status	含义	对应 --state
0	开放	open
1	已合并	merged
2	已关闭	closed

⚠️ pr +list --state 参数仅影响统计计数，返回列表可能包含所有状态。客户端需按 pull_request_status 字段过滤。

PR 合并方式

--do 参数	说明
merge	标准合并（创建 merge commit）
rebase	Rebase 合并（线性历史）
squash	Squash 合并（压缩为单个 commit）

---

二、Fork 协作流程（详细版）

何时必须 Fork

• 向非自己拥有的仓库提交 PR
• 没有目标仓库的写权限
• 即使是仓库成员，也推荐 Fork 流程

完整 Fork 工作流

# 1. Fork 目标仓库
gitlink-cli repo +fork --owner <target-org> --repo <target-repo>

# 2. 克隆自己的 Fork
git clone https://gitlink.org.cn/<my-username>/<target-repo>.git
cd <target-repo>

# 3. 添加上游 remote
git remote add upstream https://gitlink.org.cn/<target-org>/<target-repo>.git

# 4. 同步上游最新代码
git fetch upstream
git checkout master
git merge upstream/master
git push origin master

# 5. 创建功能分支
git checkout -b feature/my-change

# 6. 开发和提交
git add -A
git commit -m "feat: 我的改动"

# 7. 推送到自己的 Fork
git push origin feature/my-change

# 8. 从 Fork 向主仓库提 PR
gitlink-cli pr +create \
  --owner <target-org> --repo <target-repo> \
  --head <my-username>:feature/my-change \
  --base master \
  --title "feat: 我的改动"

# 9. 上游有更新时同步
git fetch upstream
git merge upstream/master
git push origin master

禁止操作

• ❌ 直接 clone 主仓库后 push（污染主仓库）
• ❌ 向主仓库的 master 分支直接推送
• ❌ 使用 --force push 到任何共享分支

---

三、分支命名规范

推荐命名

类型	模式	示例
新功能	feature/<描述>	feature/wiki-create
Bug 修复	fix/<描述>	fix/batch-url-encoding
文档	docs/<描述>	docs/api-reference
重构	refactor/<描述>	refactor/auth-module
发布准备	release/<版本>	release/v1.0.0
紧急修复	hotfix/<描述>	hotfix/critical-bug

GitLink 分支映射

平台	默认主分支
GitLink	master
GitHub	main

gitlink-cli 在与 GitLink 交互时自动处理映射：

• push 时：main → master
• pull 时：master → main

---

四、项目初始化清单

完整的项目初始化应覆盖以下全部：

序号	项目	命令
1	创建仓库	repo +create
2	克隆到本地	repo +clone
3	创建 README	本地创建后 git push
4	创建 .gitignore	本地创建后 git push
5	保护主分支	branch +protect --name master
6	创建开发分支	branch +create --name develop
7	创建初始 Issue	issue +create
8	创建里程碑	milestone +create
9	开启 DevOps	api POST /.../activate
10	配置流水线	创建 .devops/ 目录和 YAML 文件
11	邀请团队成员	org +batch-invite（组织仓库）或 member +add

---

五、已知限制

限制	说明
PR 创建需要代码差异	分支内容必须与目标分支不同，否则 GitLink 拒绝创建
api POST 有 URL bug	部分 Raw API 写操作不可用，优先使用 shortcuts
不能删除远程分支	branch +delete 的 API 不可用（GitLink 平台 bug）
PR state 过滤不精确	pr +list --state 仅影响计数，需客户端二次过滤

---

六、常见问题

Q: 创建 PR 时报错"无变更"？

A: 确认你的分支上有不同于 base 分支的新 commit。如果是刚创建的空白分支，先提交代码再创建 PR。

Q: PR 合并后需要手动删分支吗？

A: GitLink 目前不自动删除合并后的分支。可以用 git push origin --delete <branch> 或通过 Web 页面手动删除。

Q: 如何同步 Fork 仓库与上游？

A: git fetch upstream && git merge upstream/master && git push origin master

Q: 项目初始化后 DevOps 还是不可用？

A: api POST /activate 可能因 URL bug 失败。最可靠的方式是在 GitLink Web 页面手动开启。