The gitlab provider socket, and what it does and does not close
Status: LANDED (render-level). The socket, the SonarQube consumer and the CI-variable grant are authored and validated in-tree. Nothing in this record has been exercised against a live GitLab or a live SonarQube; see §7 for the verified/assumed split, which is the part to read before deploying.
Date: 2026-08-06. Branch agent/gitlab-socket, cut from origin/main
@ 15a72b975. SonarQube facts were measured against the pinned image
(sonarqube:26.7.0.124771-community, /api/system/info reporting
"Edition":"Community"); GitLab facts come from the 18.11 documentation
archive matching vars.images.gitlab (gitlab/gitlab-ce:18.11.7-ce.0).
1. The gap
Section titled “1. The gap”The estate had 37 sockets and GitLab was not one of them. GitLab, the
estate’s own SCM and CI, was a pure CONSUMER: libravatar, oidc,
postgres, s3, smtp. Nothing in the catalogue could integrate with it.
The visible cost was two flagship-tier apps sitting empty. apps/sonarqube
has never run a scan; apps/dependency-track is deployed at
sbom.corp.bitspur.com with no SBOM in it. Both are fed by CI, and CI is
GitLab. apps/sonarqube/sonarqube.socket.yaml had already published
hostname + port with a comment saying it existed “precisely so a CI
consumer can dial it directly”, and nothing in the catalogue consumed it,
because the consumer would have had to be GitLab.
2. What landed
Section titled “2. What landed”| File | Role |
|---|---|
apps/gitlab/gitlab.socket.yaml | The provider. Publishes the public origin + API base and MINTS a per-consumer, labelled, revocable token. |
apps/gitlab/vars.yaml, app.yaml | publicUrl, integration.user, integration.tokenDays. |
apps/sonarqube/gitlab.plug.yaml | The consumer’s intent declaration + ALM teardown. |
apps/sonarqube/sonarqube-bind-gitlab.job.yaml | post_install/post_update hook: the DevOps Platform binding. |
apps/sonarqube/sonarqube-publish-ci-variables.job.yaml | post_install/post_update hook: SONAR_HOST_URL + SONAR_TOKEN as instance CI/CD variables. |
3. Four decisions worth restating
Section titled “3. Four decisions worth restating”3.1 A singleton socket, named gitlab
Section titled “3.1 A singleton socket, named gitlab”The contract is not “an SCM”; it is GitLab’s API: /api/v4,
PRIVATE-TOKEN, GitLab’s personal-access-token scope vocabulary,
instance-level CI/CD variables. A consumer writes GitLab-shaped calls against
it, and no second implementation could satisfy them. Naming it scm or ci
would repeat worked example 1 in
docs/app-development/plugs-and-sockets.md, an OUTCOME name growing three
unrelated faces. This is rule two: the app is the capability.
3.2 vars.publicUrl exists because a socket cannot derive one
Section titled “3.2 vars.publicUrl exists because a socket cannot derive one”compose.yaml builds external_url from {{ hosts.gitlab }}, but hosts,
ports and url() are compose/plug-context names that do not exist in a
socket data: render (ce integration_render.go socketRenderCtx carries
only vars/stack/environment/tenant + connections). The render is lenient, so
a reference to one publishes an EMPTY STRING, which is how
sonarqube.socket.yaml published a blank hostname and
ivatar/libravatar.socket.yaml a blank apiUrl.
So the operator states the origin once, as matrix does with serverName and
keycloak with publicUrl. What is new here is that the socket refuses
rather than falling back: the discovery job rejects an empty value, a missing
scheme, a trailing slash, a single-label host, and the tenant alias itself. A
consumer of this socket stores url as a remote its own server and its users’
browsers both dial, and http://<env>.gitlab.<stack> resolves for neither,
which is precisely the recorded defect where the pinned frappe oidc plug wrote
an overlay alias as a browser-facing base_url and made SSO unusable behind
green jobs.
3.3 Revoke-then-mint, not create-if-absent
Section titled “3.3 Revoke-then-mint, not create-if-absent”GitLab returns a personal access token’s plaintext exactly once, at creation;
GET /api/v4/personal_access_tokens has no token field. “Create if absent”
would therefore hand the consumer an empty credential on every deploy after
the first. The mint revokes every live token carrying this consumer’s prefix
and creates exactly one replacement, so re-running any number of times leaves
exactly one live token per label, which is the property that actually matters,
and the live token is never older than the last deploy.
The mint runs gitlab-rails runner inside the provider container rather than
the REST API, because the REST route needs an administrator token to call and
that is the thing being created. There is no bootstrap API credential on the
stack. apps/gitlab/tests/tests.bats has minted its admin token this way
since it was written.
3.4 Two tokens, and only one of them is honest about being narrow
Section titled “3.4 Two tokens, and only one of them is honest about being narrow”- read:
read_api,read_repositoryby default. What an importer needs. - ci:
api, minted only for a plug that setciVariables: true.
api is “complete read and write access to the API, including all groups and
projects”. Calling it scoped would be the lie apps/mailcow/imap.socket.yaml
refuses to tell about brokerApiKey: GitLab has no per-endpoint ACL that
narrows api down to “may write CI/CD variables”, and writing instance-level
variables is an administrator-only API. What limits the exposure is lifetime,
not scope: that token is never written to SonarQube’s database, never sealed
into a vault, never rendered into compose. It exists only inside the hook that
uses it, is re-minted every deploy, and is revoked by the socket on disconnect.
4. Why the SonarQube work is in hooks, not jobs.post_deployment
Section titled “4. Why the SonarQube work is in hooks, not jobs.post_deployment”This is mechanical, and it is the single most important implementation fact in the change.
The socket mints per-consumer and returns the value on the mint-and-return
channel (::shc-connection-value::token=…::). ce folds that into the
integrations namespace with MergeJobMintedValues (install_runner.go), which
writes into the map the compose/hook render reads. A plug’s
post_deployment job renders from a different context:
runConsumerPlugPostDeploymentJobs (plug_jobs.go) builds its tmplCtx from
ic.ConsumerSocketData / ic.SocketData, the STATICALLY rendered socket data
and RunSocketIntegrationJobs iterates its contexts by value and never
writes minted values back into them.
A post_deployment job would therefore read integration.socket.data.token as
the empty string the socket publishes on purpose, POST an empty
personalAccessToken, and get HTTP 204; SonarQube performs no validation
at write time. Green job, dead binding. That is the false-success shape this
catalogue keeps finding, so the work lives where the minted value actually
arrives: the post_install/post_update hook. It is the same conclusion
imap.socket.yaml reaches for its broker capability: “a broker needs a post
hook”.
5. SonarQube: what Community Build can and cannot do
Section titled “5. SonarQube: what Community Build can and cannot do”Measured on the pin, not inferred from a feature matrix.
POST /api/alm_settings/create_gitlab (key, url, personalAccessToken) | ✅ registered, returns 204 |
| Repository IMPORT from GitLab | ✅ not gated |
| More than ONE GitLab configuration | ❌ 400 “A GITLAB setting is already defined”; multi-instance starts at Enterprise |
set_gitlab_binding / delete_binding / validate_binding | ❌ absent from the Community service registration; they 404 |
| Merge-request decoration, multi-branch analysis | ❌ Developer Edition and above |
/api/v2/dop-translation/dop-settings as a create path | ❌ read-only (POST → 405); v1 create_gitlab is still the only way at 26.x |
Consequences encoded in the job:
- It lists first (
list_definitions) and branches on the listing, never on a create error, because the singleton rule makes a second create impossible. - It adopts an existing setting in place and does not rename it.
update_gitlabaccepts anewKey, but SonarQube project bindings reference an ALM setting by key, so a rename orphans them. - It always re-sends the PAT.
list_definitionshas not returned stored secrets since 8.7, so drift can only be compared onkey+url; and an update whose URL moved is refused without one. - It finishes with
GET /api/alm_settings/validate, the only endpoint in the family that actually dials GitLab. Without it the job would report success for a binding that has never spoken to anything.
The scope narrowing is asserted rather than assumed. Sonar’s own “global
setup” page asks for the api scope, because on Developer Edition the same
token posts MR comments. Community cannot decorate, so this package asks for
read_api and lets validate be the judge, with the widen-the-scope remedy
printed in the failure.
6. CI variables: instance-level, and unprotected on purpose
Section titled “6. CI variables: instance-level, and unprotected on purpose”Reversed 2026-10-31 (FZ-8621): both variables are protected now. The first
estate to bind this found the cost the section below didn’t weigh: an
unprotected instance token reaches every job on every unreviewed branch of every
project, and shc’s and ce’s next/guard refused every pipeline for it. The
section’s argument was about merge requests, which Community Build can’t analyse
anyway: its scanner job runs on the default branch, and that’s protected. The
“green pipeline that analysed nothing” case remains for a project whose default
branch is unprotected. Instance variables take no environment scope, so that
guard’s other remedy isn’t open here. The text below is the original record.
POST /api/v4/admin/ci/variables: available on CE self-managed, administrator
only, capped at 25 instance variables by default (this uses two).
Instance-level, not group-level. Group-level is narrower, but narrower here means “the projects in one named group”, and this integration has no group to name. The bar is zero per-project and per-group setup across the estate’s whole SCM; a group write would leave every project outside that group unscanned and would need the token owner to hold Owner on the group, a membership problem a headless job cannot solve.
SONAR_TOKEN: masked: true, protected: false. The protected flag is
the setting most likely to be “corrected” later, so: a protected variable is
injected only into pipelines on protected branches and tags, and fork pipelines
never receive protected resources under any setting. A protected SONAR_TOKEN
produces exactly the outcome this lane exists to end: green pipelines that
quietly analysed nothing. SONAR_HOST_URL stays unmasked because masking it
would replace the hostname everywhere it appears in a job log; it is not a
secret.
7. Dependency-Track: the verdict (deliverable 4: ASSESSED, NOT BUILT)
Section titled “7. Dependency-Track: the verdict (deliverable 4: ASSESSED, NOT BUILT)”Verdict: the same socket closes it, and the shape is deliverable 3 ONLY; no ALM binding is involved. But it is NOT as clean as the SonarQube one, so it is written down here instead of shipped.
7.1 Why no ALM half exists
Section titled “7.1 Why no ALM half exists”Dependency-Track has no concept of importing a repository. It ingests SBOMs
that something pushes at it (POST/PUT /api/v1/bom). There is nothing
analogous to create_gitlab to call, and no wizard for the owner to be
confronted with. So dtrack needs only the CI-variable half:
DTRACK_URL = the public origin of the dtrack apiserverDTRACK_API_KEY = a team API key holding BOM_UPLOAD (+ PROJECT_CREATION_UPLOAD)with a .gitlab-ci.yml job that generates a CycloneDX SBOM and curls it up.
Structurally that is sonarqube-publish-ci-variables.job.yaml with two
different variable names, driven by the same ciVariables: true grant, the
same api-scoped token, and the same ciVariableKeys teardown contract. The
plug would be a near-copy of apps/sonarqube/gitlab.plug.yaml minus the ALM
job.
7.2 The three reasons it is not built here
Section titled “7.2 The three reasons it is not built here”- Minting the DT API key is a three-step dance, not one call. SonarQube
hands you
POST /api/user_tokens/generate→{"token":"…"}. Dependency- Track has no equivalent: a key belongs to a TEAM, so the job must find-or-create a team, grant itBOM_UPLOADandPROJECT_CREATION_UPLOAD, thenPUT /api/v1/team/{uuid}/key, and re-running has to reconcile all three without accumulating teams. Rotating means deleting the old key by its own value or uuid. That is a materially larger surface to get right blind. - DT’s admin credential path already carries an escape hatch this would
have to respect.
apps/dependency-track/vars.yamldocuments it at length: the local admin is seededadmin/adminwithforcePasswordChange, the oidc plug’s job rotates it on first run, andvars.apiKeyexists specifically for deployments whose password was changed by hand, where the job “can then neither log in nor rotate, so it fails loudly instead of guessing”. A CI-key minter has to enter through that same ladder (vars.apiKeywins outright, else local admin login, else fail), and getting that wrong on a live deployment locks the job out rather than producing a wrong value. - The public origin has the same emptiness problem, one layer deeper.
vars.apiBaseUrlis empty by default and derived from the apiserver’s own--exposebinding, and dtrack is TWO images behind one hostname with a documented ingress contract (SPA at/, apiserver under/api+/.well-known/sbom).{{ url('apiserver') }}in a hook render is probably right, but “probably” is how an unreachable URL ends up in every pipeline in the estate. It needs a live check the SonarQube path did not.
None of these is a blocker. They are three unverifiable-without-the-estate decisions stacked on a change that already carries several, and the honest move is to land the proven shape first.
7.3 What building it looks like when someone picks it up
Section titled “7.3 What building it looks like when someone picks it up”apps/dependency-track/gitlab.plug.yaml:required: false,services: [apiserver],data:carryinglabel: "dtrack-{{ tenant }}",ciVariables, andciVariableKeys: "DTRACK_URL,DTRACK_API_KEY". No ALM job, nopost_deploymentjob (same mint-and-return constraint as §4).apps/dependency-track/dtrack-publish-ci-variables.job.yaml: apost_install/post_updatehook that: enters through thevars.apiKey→ local-admin ladder; find-or-creates a team named fromvars.gitlab.ciTeam; ensuresBOM_UPLOAD+PROJECT_CREATION_UPLOAD; rotates the team key; refuses a non-publicDTRACK_URL; then writes both variables with the same create-or-update probe and the samemasked: true, protected: falseposture.- The GitLab side needs nothing new. The socket’s
ciVariableKeysteardown already removes whatever keys a consumer declares, and theapi-scoped grant is already generic. - One thing to size first: GitLab’s default cap of 25 instance-level CI/CD
variables. SonarQube takes two, dtrack would take two. The cap is only
movable from a Rails console (
Plan.default.actual_limits.update!), so a catalogue that grows a dozen of these consumers will hit it, and the socket should probably learn to count before that happens.
8. Verified vs assumed
Section titled “8. Verified vs assumed”Verified in this change:
- Every SonarQube claim in §5 (endpoint registration, parameter names, the
204-on-empty-token behaviour, the singleton 400, the missing
set_gitlab_binding, the/api/v2read-only surface, and the accepted authentication forms), measured againstsonarqube:26.7.0.124771-community. - The ce render-context claims in §3.2 and §4, read from the pinned ce module
(
integration_render.go,socket_jobs.go,plug_jobs.go,install_runner.go) rather than from documentation. - That every template in the change renders:
cmd/validate-templates ./apps, plus a direct render of the socketdata:block, the plugdata:block and every job’s command/env against a realistic context. - That every shell body is POSIX-valid (
sh -n) and bothgitlab-rails runnerprograms parse (ruby -c). sh scripts/arch-fitness.shandgo test ./tests/unit/catalog/clean.
Assumed: nothing below has run against a live server:
- That
read_apisuffices for SonarQube’s global PAT on Community Build. Sonar documentsapi. The bind job’svalidatecall is the assertion that turns this into a measurement on first deploy, with the remedy printed. - That
personal_access_tokens.create!(...).tokenreturns the plaintext in agitlab-rails runnerprocess at 18.11. The in-tree bats helper does exactly this, so it is proven for that path, not re-proven here. - That
t.revoke!exists onPersonalAccessTokenat 18.11 (there is anupdate_columnsfallback) and thatCi::InstanceVariableis the model name for instance CI/CD variables (guarded withdefined?). - That GitLab accepts a 365-day
expires_aton this instance. The mint retries at 30 days if it does not. - That a container-context hook job resolves
sonarqubeby short name. The identical shape ships today inapps/sonarqube/saml.plug.yaml, so the risk is low, but the hook path specifically has not been exercised. - That
url('sonarqube')yields the public origin in a hook render.apps/wordpress/wordpress-init.job.yamldoes this in apost_installhook, so the callable is available; the value on this estate is unmeasured. - Every GitLab API detail in §6 comes from the 18.11 documentation archive, not from a call.