GitLab Support

GitLab Support

Since 1.0, SpecGit is dual-platform: GitHub.com and self-managed GitLab CE/Free. Every behavioral claim is pinned in the committed evidence ledger docs/evidence/gitlab-19.2.md.

Supported version range

• Self-managed GitLab is supported at exactly >= 19.2.4 < 19.3.0, CE/Free tier. Known-good anchor: release tag v19.2.4-ee (commit 85f4a2d9). Any other version fails closed with gitlab_version_unsupported (exit 3). The window moves only through an explicit rebaseline delivery — never silent drift.
• The -ee/-ce suffix is a release-channel marker, not semver pre-release: comparison strips the suffix, then compares the x.y.z triple.
• Version discovery uses the authenticated metadata endpoint (glab api /metadata).
• glab floor: 1.113.0, authenticated per host (glab auth status --hostname <host>).
• GitLab.com (SaaS) is judged by capability probing, never version pinning.

Declaration

The platform is declared, never guessed:

specgit init --gitlab-host git.example.com          # bare hostname
specgit init --gitlab-host git.example.com:8443     # non-default port

The declaration persists to spec_git/providers.yaml (gitlab.host, optional gitlab.port) and is committed, so the team shares it. Nested-group origins (group/subgroup/project, depth 2–5, %2F-encoded separators included) are first-class. init in GitLab mode writes every platform-neutral harness asset but no GitHub Actions workflow (gitlab_harness_pending warning) — the repo carries its own .gitlab-ci.yml, whose top-level job keys are detected as required checks.

Differences from GitHub

Aspect	GitHub	GitLab
Evidence CLI	gh	glab (≥ 1.113.0, per-host auth)
Merge request	PR	MR, drafts via Draft: title prefix
Checks	check runs at the PR head	pipeline jobs mapped to checks (job name = check name); allow_failure failure passes per pipeline semantics; skipped produces no check run
Required checks	required status checks	the verified pipeline-gate intersection (only_allow_merge_if_pipeline_succeeds); Ultimate-only status checks are never used
Closing references	full keyword/URL grammar	common subset — Closes #<iid> / Fixes #<iid> — valid on both platforms
Harness	.github/workflows/specgit-accept.yml	your own .gitlab-ci.yml (template is future work); a read-only project access token (read_api) authenticates glab in CI
Failure codes	gh_missing, gh_unauthenticated, gh_transport	glab_missing, glab_unauthenticated, glab_transport, plus gitlab_version_unsupported

Environment and non-goals

• SPECGIT_GLAB (executable path) and SPECGIT_GLAB_TIMEOUT_MS (default 15000; timeout ⇒ glab_transport, exit 3).
• Fail-closed carries over: missing glab, unauth, out-of-range version, unreachable instance ⇒ unknown, never accepted.
• Non-goals: no cross-platform deliveries (one delivery, one platform, one PR/MR); no token storage; no Ultimate-tier primitives, ever.

---

GitLab 支持

从 1.0 起 SpecGit 双平台：GitHub.com 与自建 GitLab CE/Free。所有行为声明都钉在已提交的证据台账 docs/evidence/gitlab-19.2.md 中。

支持的版本范围

• 自建 GitLab 仅在 >= 19.2.4 < 19.3.0、CE/Free 层级下受支持。 已知可用锚点：release tag v19.2.4-ee（commit 85f4a2d9）。其他版本一律 fail-closed，报 gitlab_version_unsupported（退出 3）。版本窗口只通过显式的 rebaseline 交付移动 —— 绝不静默漂移。
• -ee/-ce 后缀是发布渠道标记，不是 semver 预发布语义：比较时先剥离后缀，再比较 x.y.z 三元组。
• 版本发现走已认证的 metadata 端点（glab api /metadata）。
• glab 最低版本 1.113.0，按主机认证（glab auth status --hostname <host>）。
• GitLab.com（SaaS）按能力探测判定，不做版本钉死。

声明方式

平台是声明出来的，不是猜的：

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

声明持久化到 spec_git/providers.yaml（gitlab.host，可选 gitlab.port）并提交，团队共享。嵌套组 origin（group/subgroup/project，深度 2–5，含 %2F 编码分隔符）是一等公民。GitLab 模式下 init 会写入所有平台中立的护栏资产，但不写 GitHub Actions 工作流（警告 gitlab_harness_pending）—— 仓库自带 .gitlab-ci.yml，其顶层 job key 会被检测为必需检查。

与 GitHub 的差异

方面	GitHub	GitLab
证据 CLI	gh	glab（≥ 1.113.0，按主机认证）
合并请求	PR	MR，草稿用 Draft: 标题前缀
检查	PR head 上的 check runs	pipeline jobs 映射为检查（job 名 = 检查名）；allow_failure 的失败按 pipeline 语义放行；skipped 不产生 check run
必需检查	required status checks	已验证的 pipeline 门禁交集（only_allow_merge_if_pipeline_succeeds）；永不使用 Ultimate 专属 status checks
关闭引用	完整的关键词/URL 语法	公共子集 —— Closes #<iid> / Fixes #<iid> —— 两平台均有效
护栏	.github/workflows/specgit-accept.yml	仓库自带 .gitlab-ci.yml（模板属未来工作）；CI 中用只读 project access token（read_api）认证 glab
失败码	gh_missing、gh_unauthenticated、gh_transport	glab_missing、glab_unauthenticated、glab_transport，另有 gitlab_version_unsupported

环境与非目标

• SPECGIT_GLAB（可执行文件路径）和 SPECGIT_GLAB_TIMEOUT_MS（默认 15000；超时 ⇒ glab_transport，退出 3）。
• Fail-closed 同样适用：glab 缺失、未认证、版本越界、实例不可达 ⇒ unknown，绝不 accepted。
• 非目标：不跨平台交付（一次交付、一个平台、一个 PR/MR）；不存储 token；永不使用 Ultimate 层级能力。