git分支名必须含jira编号且前置，如feature/proj-123-add-login；编号大小写敏感、不可简写或拼接，否则gitlab推送拦截、ci解析失败、jira状态无法自动更新。

Git 分支名必须匹配正则才能推送

Git 本身不校验分支名，但 GitLab 可通过 Push rules 强制拦截不合规的分支创建。如果 CI/CD 流水线依赖分支名解析 Jira 编号，而分支名未通过正则校验，就会直接被拒绝推送，连 PR 都建不出来。

常见正则配置（GitLab → Settings → Repository → Push rules → Branch name）：

^feature\/[A-Z]+-[0-9]+-.+|^bugfix\/[A-Z]+-[0-9]+-.+|^hotfix\/.+-[0-9]{8}$

• feature\/[A-Z]+-[0-9]+-.+ 匹配 feature/PROJ-123-add-login，但会拒绝 feature/add-login-PROJ-123（编号不在开头）
• 大小写敏感：PROJ-123 合法，proj-123 或 PROJ-123 中字母大小写混用（如 PrOj-123）会被拒
• 不支持空格或中文，feature/PROJ-123 用户登录 直接失败
• 正则末尾没加 $ 容易漏匹配，比如 ^feature\/[A-Z]+-[0-9]+- 会错误放行 feature/PROJ-123-extra-suffix 以外的非法变体

Jira 编号提取失败导致 CI 自动化中断

CI 脚本通常用 sed 或 grep -oE 从 git branch --show-current 结果里抽编号，例如：

git branch --show-current | grep -oE '[A-Z]+-[0-9]+'

一旦分支名不符合预期格式，这个命令就返回空，后续所有自动拉取 Jira 描述、生成发布说明、设置告警等级的操作都会跳过或报错。

Git

程序猿必备版本控制工具

下载

• 编号放在末尾（feature/add-search-PROJ-456）→ 正则匹配不到，CI 认为“无关联 ticket”
• 多个编号拼接（feature/PROJ-123-and-PROJ-456）→ grep -oE 可能只取第一个，或因分隔符不明确导致解析异常
• 编号简写（feature/PROJ-123 写成 feature/123）→ 正则根本无法命中，CI 日志里出现 ticket_id is empty
• 项目 Key 大小写错误（Jira 实例是 MATERIAL，却写了 material-123）→ Jira API 返回 404，CI 卡在请求环节

GitLab + Jira 自动化联动失效的隐蔽原因

即使分支名和提交信息都写了 PROJ-123，Jira 里仍不显示关联提交或不自动更新状态，问题往往不在连接配置，而在细节断点。

• Jira 的 Transition ID 配置错误：比如设了 31（In Progress），但当前 issue 状态是 To Do，而 To Do → In Progress 的合法 transition ID 实际是 21，跳转会静默失败
• 提交信息未触发关键词：GitLab 默认只识别 closes PROJ-123、fixes PROJ-123 这类前缀，PROJ-123: fix login bug 不会触发状态变更
• Jira issue resolution 字段非空：若 issue 已被手动标记为 Done 或 Resolved，GitLab 的自动化状态流转会被跳过（这是设计行为，不是 bug）
• GitLab token 权限不足：用于集成的 Personal Access Token 缺少 api 或 read_issue 权限，Jira 页面显示“关联提交 0 条”，但 GitLab 后台日志里只有 HTTP 403

本地开发时分支命名容易忽略的硬约束

开发者在本地 git checkout -b 时觉得“先随便起个名，推上去再改”，但实际很多约束是推送时才生效，本地操作完全无感知，直到 git push 被拒才暴露问题。

• 不能用 _ 替代 -：虽然 Git 允许，但 Jira 解析器和 CI 正则通常只认连字符，feature/PROJ_123 会被当作文本而非 ticket ID
• 日期格式必须严格：hotfix 分支要求 hotfix/payment-gateway-20241124，写成 241124 或 2024-11-24 都不匹配预设正则
• 业务简称不能缩写过度：规范要求 feature/order-create-JIRA-1234，写成 feature/oc-JIRA-1234 会导致语义丢失，Code Review 时被 reject，且影响后续审计追溯
• 本地分支名与远程同名但格式不同：比如本地建了 feature/proj-123-login，推送到远程时 GitLab 拒绝，但本地 git branch 仍显示该分支——需手动删掉重来，否则下次 git push 还会尝试推同样非法名

真正卡住团队节奏的，往往不是技术实现难度，而是编号位置、大小写、连字符这些看似微小的格式细节——它们在自动化链条里是原子级开关，错一个，整条流水线就停摆。