Skip to content
SHC Docs

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).


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.

FileRole
apps/gitlab/gitlab.socket.yamlThe provider. Publishes the public origin + API base and MINTS a per-consumer, labelled, revocable token.
apps/gitlab/vars.yaml, app.yamlpublicUrl, integration.user, integration.tokenDays.
apps/sonarqube/gitlab.plug.yamlThe consumer’s intent declaration + ALM teardown.
apps/sonarqube/sonarqube-bind-gitlab.job.yamlpost_install/post_update hook: the DevOps Platform binding.
apps/sonarqube/sonarqube-publish-ci-variables.job.yamlpost_install/post_update hook: SONAR_HOST_URL + SONAR_TOKEN as instance CI/CD variables.

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_repository by default. What an importer needs.
  • ci: api, minted only for a plug that set ciVariables: 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_gitlab accepts a newKey, but SonarQube project bindings reference an ALM setting by key, so a rename orphans them.
  • It always re-sends the PAT. list_definitions has not returned stored secrets since 8.7, so drift can only be compared on key + 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.

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 apiserver
DTRACK_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”
  1. 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 it BOM_UPLOAD and PROJECT_CREATION_UPLOAD, then PUT /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.
  2. DT’s admin credential path already carries an escape hatch this would have to respect. apps/dependency-track/vars.yaml documents it at length: the local admin is seeded admin/admin with forcePasswordChange, the oidc plug’s job rotates it on first run, and vars.apiKey exists 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.apiKey wins 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.
  3. The public origin has the same emptiness problem, one layer deeper. vars.apiBaseUrl is empty by default and derived from the apiserver’s own --expose binding, 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: carrying label: "dtrack-{{ tenant }}", ciVariables, and ciVariableKeys: "DTRACK_URL,DTRACK_API_KEY". No ALM job, no post_deployment job (same mint-and-return constraint as §4).
  • apps/dependency-track/dtrack-publish-ci-variables.job.yaml: a post_install/post_update hook that: enters through the vars.apiKey → local-admin ladder; find-or-creates a team named from vars.gitlab.ciTeam; ensures BOM_UPLOAD + PROJECT_CREATION_UPLOAD; rotates the team key; refuses a non-public DTRACK_URL; then writes both variables with the same create-or-update probe and the same masked: true, protected: false posture.
  • The GitLab side needs nothing new. The socket’s ciVariableKeys teardown already removes whatever keys a consumer declares, and the api-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.

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/v2 read-only surface, and the accepted authentication forms), measured against sonarqube: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 socket data: block, the plug data: block and every job’s command/env against a realistic context.
  • That every shell body is POSIX-valid (sh -n) and both gitlab-rails runner programs parse (ruby -c).
  • sh scripts/arch-fitness.sh and go test ./tests/unit/catalog/ clean.

Assumed: nothing below has run against a live server:

  • That read_api suffices for SonarQube’s global PAT on Community Build. Sonar documents api. The bind job’s validate call is the assertion that turns this into a measurement on first deploy, with the remedy printed.
  • That personal_access_tokens.create!(...).token returns the plaintext in a gitlab-rails runner process 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 on PersonalAccessToken at 18.11 (there is an update_columns fallback) and that Ci::InstanceVariable is the model name for instance CI/CD variables (guarded with defined?).
  • That GitLab accepts a 365-day expires_at on this instance. The mint retries at 30 days if it does not.
  • That a container-context hook job resolves sonarqube by short name. The identical shape ships today in apps/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.yaml does this in a post_install hook, 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.