Skip to content

GitLab Support zh

Jump to bottom
Lex edited this page Aug 21, 2026 · 2 revisions

GitLab 支持

v1 范围：GitHub.com 加自建 GitLab CE/Free，版本恰好在 >= 19.2.4 < 19.3.0 区间内。 GitLab 证据经已认证的 glab CLI（≥ 1.113.0）流动，正如 GitHub 证据经 gh 流动。一套 CLI、一套护栏、两个 forge —— 平台是声明出来的，不是猜出来的。

声明 GitLab origin

specgit init --gitlab-host git.example.com          # 裸主机名
specgit init --gitlab-host git.example.com:8443     # 非默认端口

声明持久化在 spec_git/providers.yaml 并提交，团队共享。github.com origin 无需声明。认证按主机进行：

glab auth login --hostname git.example.com
glab auth status --hostname git.example.com

环境契约（与 GitHub 侧镜像）：SPECGIT_GLAB（可执行文件路径）和 SPECGIT_GLAB_TIMEOUT_MS（默认 15000；超时 ⇒ glab_transport，退出码 3）。

版本窗口

  • 自建 GitLab 的支持版本恰好是 >= 19.2.4 < 19.3.0，CE/Free 层级。已知良好锚点：v19.2.4-ee 发布标签。
  • 区间外的任何版本都 fail-closed：gitlab_version_unsupported，退出码 3。窗口只能通过显式的 rebaseline 交付移动 —— 绝不静默漂移。
  • -ee / -ce 后缀是发布通道标记，不是 semver 预发布语义：版本比较先剥离后缀，再比较 x.y.z 三元组。
  • 版本发现使用已认证的 metadata 端点（glab api /metadata）；metadata.enterprise 仅供参考，绝不作为关卡输入。
  • glab 下限：1.113.0。
  • GitLab.com（SaaS）按能力探测判定，绝不做版本钉死 —— 任何探测失败 ⇒ 结论 unknown（退出码 3）。

与 GitHub 的差异

方面 GitHub（gh） GitLab（glab）
Pull request Pull request Merge request，创建时标题带 Draft: 前缀
Origin 语法 owner/repo group[/subgroup…]/project，深度 2–5，支持 %2F 编码分隔符
护栏 init 生成 .github/workflows/specgit-accept.yml 不写 GitHub workflow（gitlab_harness_pending）；自带 .gitlab-ci.yml —— 其顶层 job key 被探测为必需检查
Check runs PR 头上的 GitHub check runs 流水线 job 映射为检查：job 名 = 检查名；skipped 不产生 check run；失败的 allow_failure job 按流水线语义通过关卡；非终态一律视为 pending，fail-closed
必需检查的事实来源 必需状态检查 开启 only_allow_merge_if_pipeline_succeeds 时，策略列表与最新流水线 job 名的已验证交集；绝不使用 Ultimate 专属的状态检查原语
关闭引用 完整 GitHub 语法 公共子集：Closes #<iid>、Fixes #<iid> —— 两个平台都有效
项目标识 owner/repo 完整路径 URL 编码（/ → %2F）作为 :id，并用数字项目 id + 路径比对验证
未声明的 origin 不适用 任何深度都 fail-closed 为 gitlab_unsupported

声明的 GitLab origin 上，specgit finish 通过 glab 评估全部十一个关卡；specgit issue 引导对 GitLab 可用（推送分支后创建草稿 MR，使用公共子集关闭引用）。诊断码跟随平台 CLI：glab_missing、glab_unauthenticated、glab_transport、gitlab_version_unsupported。

设计原则

  1. 镜像接缝，不分叉关卡。 验收评估是平台无关的；只有证据收集是平台相关的。
  2. 每个平台一个 CLI，已认证，状态与日志中没有 token。 没有直接的 REST 客户端。
  3. Fail-closed 一脉相承。 glab 缺失、glab 未认证、服务器版本超出区间或实例不可达，都产生 unknown，绝不产生 accepted。静默的分页部分列表绝不被消费（evidence_truncated，退出码 3）。
  4. 只用 Free 层级原语，并如实报告。 Ultimate 专属功能永远排除。

非目标

  • 不做跨平台交付（一次交付、一个平台、一个 PR/MR）。
  • 不存储 token：glab 自己管理凭证，与今天的 gh 相同。
  • 没有 rebaseline 交付就不支持 >= 19.2.4 < 19.3.0（自建）之外的版本；永远不用 Ultimate 层级原语。
  • GitHub Enterprise 仅支持声明与诊断（v1 非目标）。

英文版：GitLab-Support

SpecGit Wiki

中文

Repository documentation

Clone this wiki locally