Git Workflow Knowledge Base

Foundational guidance for Git version control workflows, branching strategies, commit conventions, and collaborative development.

Source: Extends netresearch/git-workflow-skill v1.18.8 (CC-BY-SA-4.0). Team-specific rules overlay on top.

架构分层

┌─────────────────────────────────────────────┐
│  下游技能（extends 本基座）                    │
│  devlab-git-workflow-expert 等               │
├─────────────────────────────────────────────┤
│  团队规范叠加层（本文件 §团队规范章节）          │
│  commit 规范 / 分支策略 / Gitea / 镜像同步     │
├─────────────────────────────────────────────┤
│  上游通用知识（netresearch/git-workflow-skill） │
│  branching / commits / PR / CI / hooks       │
└─────────────────────────────────────────────┘

Workflow

1. Determine the workflow model (Git Flow / GitHub Flow / Trunk-based).
2. Create branch following naming conventions (Section: Branch Naming).
3. Make atomic commits with Conventional Commits (Section: Commit Conventions).
4. Push and open PR with proper description (Section: PR Workflow).
5. Ensure CI green + all review threads resolved before merge.
6. Merge with appropriate strategy — feature PR 默认 squash（见 §PR Workflow）。
7. Release 打 tag：v{major}.{minor}.{patch}（见 §Release & Tag）。

Critical Rules (Non-Negotiable)

1. No direct push to main — always open a PR.
2. No merge before all threads resolved — see references/pull-request-workflow.md.
3. Feature PR 默认 squash merge — 开发分支历史压缩为一个干净 commit；release/hotfix 保留完整历史。
4. No "tested/verified" without pasted command output — else say so explicitly.
5. Force-push only with --force-with-lease — never plain --force.
6. Commit before rebase — add → commit → fetch → rebase → push. Dirty tree aborts rebase.
7. No editorializing — state what changed, not how good it is.
8. Gitea-first — git clone 和 git remote 优先使用 Gitea 内网地址，避免直连 GitHub。
9. 内网镜像优先 — git clone 时优先 Gitea 内网镜像 URL，减少公网流量和延迟。

Commit Conventions

上游 Conventional Commits

<type>[scope]: <description>

[optional body]

[optional footer(s)]

Types: feat (MINOR), fix (PATCH), docs, style, refactor, perf, test, build, ci, chore, revert

Breaking change: Add ! after type or BREAKING CHANGE: in footer.

团队叠加规范

在通用 Conventional Commits 基础上，团队额外约定：

1. scope 使用组件/模块 ID：如 feat(cli):, fix(compose-app-deploy):, docs(harness-ai-kit-forge):
2. description 使用中文或英文均可，但同一 PR 内保持一致
3. 多变更拆原子 commit：一个 commit 做一件事，便于 bisect 和 revert
4. commit body 说明 why：type+scope 说明 what，body 说明 why（非显而易见时）
5. CHANGELOG 由 commit 自动生成：feat/fix/BREAKING CHANGE 会出现在 CHANGELOG 中

References:

• team-commit-conventions

Branch Naming

feature/TICKET-123-description
fix/TICKET-456-bug-name
release/1.2.0
hotfix/1.2.1-security-patch
docs/update-skill-guide
refactor/simplify-auth-flow

团队分支策略选择

项目类型	推荐策略	理由
个人工具/脚本仓库	Trunk-based（直接 main）	轻量，无需 PR 流程
CLI / Skill / 正式项目	GitHub Flow（feature → main）	PR review + CI gate
多人协作 / 生产服务	Git Flow（develop + release + hotfix）	完整发布管理

团队特殊约定

• 02-工程工作空间：大部分子项目使用 Trunk-based 或 GitHub Flow
• fleet-platform / 控制仓：必须 PR + review，禁止直推 main
• harness-ai-kit skills 仓库：PR + CI gate，merge 后自动 publish

References:

• team-branch-strategy

PR Workflow

上游规则（netresearch/git-workflow-skill）

1. Default-branch check before PR operations
2. Atomic commits, no squash unless asked
3. Merge strategies: merge / squash / rebase
4. Review thread resolution mandatory
5. Merge gate: CI green + threads resolved + rebased + signed

团队叠加

• PR 标题遵循 commit convention：feat(cli): add shared-resources command
• PR body 包含变更摘要和影响范围
• Gitea PR：使用 tea pr create 或 REST API，参考 giteactl 技能
• 自审 checklist：merge 前自行检查 — 无遗留 TODO、测试通过、文档更新

合并策略（来自踩坑纠正）

场景	策略	理由
Feature PR → main	squash merge（默认）	历史干净，一个 feature 一个 commit
Release branch → main	merge commit	保留 release 完整历史
Hotfix → main	merge commit	保留修复上下文
小修小补（typo/docs）	rebase (fast-forward)	线性历史

注意：上游 netresearch/git-workflow-skill 默认 no squash。本团队覆盖为 feature PR 默认 squash，release/hotfix 保留 merge commit。

References:

• team-pr-workflow

Release & Tag

Tag 命名规范（来自踩坑纠正）

v{major}.{minor}.{patch}

示例	含义
v1.0.0	首个正式版
v1.2.3	patch 修复
v2.0.0-rc.1	预发布候选
v0.1.0	draft/trial 阶段

规则：

• Tag 必须带 v 前缀
• 严格遵循 SemVer（语义化版本）
• 打 tag 前确保 CI green、CHANGELOG 已更新
• git tag -a v1.2.3 -m "release: v1.2.3" 使用 annotated tag（不用 lightweight）
• 推送 tag：git push origin v1.2.3

Tag 触发 CI Release

• Woodpecker：.woodpecker.yml 配置 when: { event: tag } 触发 release pipeline
• Jenkins：Jenkinsfile 配置 tag filter 触发 release build

多仓协同（来自高频踩坑）

团队日常在多个 Git 仓库间切换（Gitea 镜像、server-apps、控制仓、应用仓），86% 会话涉及多仓操作。

目录结构规范

~/repos/
├── gitea/           # Gitea 内网仓库
│   ├── server-apps/
│   ├── fleet-platform/
│   └── my-app/
└── github/          # GitHub 开源/镜像
    └── open-source-project/

多仓操作最佳实践

1. 按 remote 分目录：gitea/ vs github/，避免混淆
2. 使用 git worktree：同一仓库多分支并行开发（详见 REFERENCE-ADVANCED-GIT.md）
3. 批量状态检查：for d in */; do echo "=== $d ==="; git -C "$d" status -s; done
4. 统一 remote 命名：origin = 主 remote（Gitea），upstream = 上游（GitHub）

References:

• multi-repo

CI/CD Integration

上游规则

• Watching CI from CLI: gh pr checks, gh run watch
• Git mirror repository sync: git push --mirror gotchas

团队叠加

• Woodpecker CI：Team 项目主要 CI，使用 .woodpecker.yml
• Jenkins：Java 项目 + shared library，使用 Jenkinsfile
• Git mirror sync：Gitea ↔ GitHub 双向镜像，注意 --mirror 会覆盖所有 refs

References:

• team-ci-cd

Git Hooks

上游支持

Detect hooks first:

ls lefthook.yml .lefthook.yml captainhook.json .pre-commit-config.yaml .husky/pre-commit 2>/dev/null || echo "No hooks"

Install: lefthook install | composer install | npm install | pre-commit install

团队叠加

• 优先使用 lefthook（跨语言、配置简洁）
• Python 项目可配合 pre-commit + ruff/black/isort
• 提交前必须通过 hook 检查：commit message 格式 + 基础 lint

Advanced Operations

Reference:

• advanced-git — rebase, cherry-pick, bisect, stash, worktrees, reflog, recovery

Gitea 工作流

团队内部 Git 平台为 Gitea，与 GitHub 的差异：

操作	GitHub	Gitea
CLI	gh	tea / giteactl
PR 创建	gh pr create	tea pr create 或 REST API
Mirror	git push --mirror	Gitea 内置镜像同步
Webhook	GitHub Actions	Woodpecker CI
Token	Personal Access Token	API Token（Settings → Applications）

References:

• team-gitea-workflow

Guardrails

• Never force-push to main/master without explicit user approval.
• Never use plain --force — always --force-with-lease.
• Never push secrets, tokens, or credentials in commits.
• Never skip CI checks before merge — ensure all gates green.
• Never use merge commit for feature PRs — use squash merge.
• Never use dev/xxx or unprefixed branch names — always feature/xxx, fix/xxx, etc.
• Never git clone from GitHub when a Gitea internal mirror exists.
• Prefer git pull --rebase over git pull to avoid merge commits on feature branches.
• Use git add -p for interactive staging when changes span multiple concerns.

参考文档：

• references/REFERENCE-README.md