GitHub Flow核心是main分支永远可部署，禁止直接推送，PR必须经CI验证后合并；分支需规范命名（如feat/、fix/），PR描述须含测试清单与issue关联，CI须监听main及特性分支。
GitHub Flow 不是“简化版 GitFlow”，它压根就不是为版本号或周期发布设计的——如果你的项目需要打 v2.3.1 标签、要回滚到上个季度的稳定包、或者测试环境必须和生产环境严格隔离，那 GitHub Flow 会很快让你踩坑。
main 分支必须永远可部署，否则整个流程失效
这是 GitHub Flow 的铁律，不是建议。一旦有人 git push origin main 直接提交，CI 没跑完、测试没过、甚至没写单元测试，后续所有 PR 合并都会基于一个不可信基线。
- CI 必须在
pull_request和push到main两个事件上都触发，且失败时禁止合并 - 禁止配置
allow bypassing pull requests这类仓库设置（GitHub Settings → Branches → Branch protection rules） -
main分支的推送权限应仅限于 CI/CD 流水线（如通过github.actor == 'github-actions[bot]'鉴权），而非开发人员
feature 分支命名不是风格问题，而是自动化前提
GitHub Actions、GitVersion、甚至内部部署脚本，往往依赖分支名做路由判断。用 abc123 或 my-branch 这类无意义名称，等于关掉了自动识别功能。
Convert Github Repository
下载
适用于以下场景：（1）用户提供 GitHub 仓库 URL 或本地仓库路径，并请求将其转换为其他格式；（2）用户请求导出 GitHub 仓库……
- 推荐格式：
feat/user-profile-api、fix/login-timeout、chore/update-deps - 避免空格、大写字母、中文、特殊符号（
!、@、~）——这些在 CI 脚本里容易引发 shell 解析错误 - 如果用了
GitVersion，它只认feat/*、fix/*、hotfix/*前缀来推导预发布版本号，其他前缀一律视为0.0.0
PR 描述模板不是走形式，而是防止遗漏关键动作
一个没写测试清单的 PR，大概率意味着“我本地跑过了”，但 CI 环境可能缺依赖、时区不同、或 Node.js 版本不一致。
- 必须包含明确的
Closes #xxx或Resolves #xxx，否则 issue 状态不会自动关闭 - 测试清单项要具体：
[x] 登录接口返回 401 时前端显示「令牌过期」提示，而不是笼统的[x] 功能测试通过 - 涉及数据库变更时，必须注明是否含 migration 文件、是否需手动执行、是否兼容旧数据
CI 配置里最容易被忽略的陷阱：on.push 的分支范围
很多团队只监听 main，结果特性分支上已暴露的 bug（比如依赖冲突、ESLint 报错）拖到 PR 阶段才被发现，拉长反馈周期。
- 正确做法是同时监听：
on: { push: { branches: ['main', 'feat/**', 'fix/**'] } } - 但要注意：GitHub Actions 对
**通配符不支持嵌套层级限制，feat/**会匹配feat/a/b/c—— 如果你不需要这么深，改用feat/*更可控 - 若使用
npm ci，确保package-lock.json已提交，否则npm install在不同机器上可能装出不同版本
GitHub Flow 看似简单，但它的脆弱点全藏在自动化链路的衔接处：分支命名影响 GitVersion 输出，PR 描述影响 issue 闭环，CI 触发范围影响问题发现时机。少一个环节对齐，就不是“轻量”，而是“漏检”。
