docs(gitlab): warn that web-commit signing needs project opt-in

Real-world testing surfaced release commits landing Unverified on
gitlab.com despite a valid token: the per-project/group "Sign
web-based commits" setting is off by default and is required in
addition to the 18.10+ instance version. Document the prerequisite
in the GitLab CI guide and record an erratum on ADR-058, which had
framed the instance version as the sole gating factor.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: mscharley

docs/adr/058-verified-release-commits-on-gitlab-via-web-commits-api.md

@@ -176,3 +176,9 @@ Rejected on three grounds. First, the two APIs differ substantively in shape: Gi
 Rather than relying on either forge's web-commit signing, cursus could ship a signing key (e.g., embedded in the binary or fetched from a per-project location) and sign commits locally before pushing via either forge's normal git transport.
 
 Rejected for the same key-custody reasons as the first alternative above, with the additional drawback that it duplicates work both forges have already done well. The forges already maintain a publicly-discoverable trust root for their own web-commits keys; building a parallel cursus-specific trust root would be a strictly inferior version of that.
+
+## Errata
+
+### 2026-05-24: Instance version is not the only signing prerequisite — a per-project/group setting is also required
+
+The "Best-effort signing on older self-managed instances" section frames the GitLab instance version (18.10+, when `configure_web_based_commit_signing` went GA) as the sole gating factor for whether an API-created commit is signed. That is functionally incorrect: signing also requires the **"Sign web-based commits"** setting to be explicitly enabled at the project or group level (Settings → Repository → General), and that setting is OFF by default. Real-world testing on GitLab.com with a valid `GITLAB_TOKEN` confirmed this — the `GitLabSignedCommit` decorator behaved correctly (it omits `author_email`/`author_name` as required, and the commit was accepted rather than rejected, proving the author fields are not at fault), yet the landed commit showed as Unverified because the per-project setting was off. On a fully up-to-date GitLab.com instance the version gate is already satisfied, so this opt-in setting is in practice the more likely tripwire. The "best-effort signing" contract and the no-runtime-probe decision are unchanged; only the framing of what users must enable to actually get a Verified commit is corrected here. The user-facing GitLab integration documentation has been updated to warn about this project/group setting as a prerequisite.

docs/site/src/content/docs/guides/ci-integration/gitlab.md

@@ -90,9 +90,14 @@ When Cursus detects it is running on GitLab CI (`GITLAB_CI=true`) with a token a
 Requirements:
 
 - **GitLab 18.10 or later.** Older versions accept the API call but do not produce a Verified signature.
+- **"Sign web-based commits" must be enabled on the project or its group.** This setting is **off by default**, even on gitlab.com running a current version. Without it, the API commit lands successfully but appears **Unverified** with no signature at all. Enable it under **Settings → Repository → General → Sign web-based commits** (project level requires the Maintainer or Owner role; enabling it at the group level applies to every project in the group and disables the per-project checkbox). See [GitLab's web-commit signing docs](https://docs.gitlab.com/user/project/repository/signed_commits/web_commits/) for details.
 - A project- or group-access token, or `CI_JOB_TOKEN`. No long-lived signing key custody is required.
 - The token's user identity is what GitLab records as the author and committer; `author_email` / `author_name` are deliberately omitted from the request so GitLab can sign the commit.
 
+:::caution
+If your release commits show as Unverified despite running on GitLab 18.10+ with a valid token, the most likely cause is that **Sign web-based commits** has not been enabled on the project or group. The commit succeeds either way, so there is no error to alert you — the only signal is the missing Verified badge.
+:::
+
 To opt out, set `[git].signed_commits = "off"` in `.cursus/config.toml`. To force the API path outside CI (e.g. for local testing against a dev instance), set `[git].signed_commits = "force"`.
 
 ## Releases vs draft releases