Skip to content

GitLab: Transactional Source & Release Authority

Role in the context plane

GitLab is the transactional source and release truth for the Bluefly estate — live repository content, merge requests, pipelines, packages, releases, CI components, webhooks, and service-account identity. This file documents GitLab's role as a context source an agent queries, not the GitLab CI Engineering Standard or the repository inventory (catalog/gitlab-repos.md) — read those for the respective contracts they own.

GitLab stays transactional source/release truth. Orbit stays derived/advisory graph. The two must never collapse into one thing — see Orbit Specification for the distinction.

Authority

Authoritative — the live GitLab API/UI state of a repository, MR, pipeline, package, or release is the fact. No cache, index, or graph projection overrides it.

Query/access path

  • Live repository, branch, MR, pipeline, package state: glab api / glab mr/glab pipeline / GitLab REST API — always current, always live.
  • CI components consumed via include: component: (see blueflyio/gitlab_components) — the shared CI template authority; a shared-signature CI failure is fixed there once, never patched per-consumer.
  • Service-account identity: each agent authenticates as its assigned blucity_<role> GitLab service account — see Identity Contract.
  • Package/Composer/npm registry metadata (what version is actually published) — live GitLab package registry state, not a local composer.lock/package-lock.json assumption.

Freshness

TRANSACTIONAL/LIVE. Every read is a live API call; there is no staleness window by design. (Contrast Orbit: POINT-IN-TIME/derived, and QMD: INDEXED/DERIVED.)

Mutation boundary

WRITE_ALLOWED=YES, governed. All durable changes go through branch → commit → MR → CI → merge to the target release branch (never direct pushes to main/release/v0.1.x protected branches). A GitLab service-account token is scoped per project/group job-token allowlist — see the Failure Signature Catalog for the job-token-scope and group-facade-auth failure signatures this produces when misconfigured.

Relationship to other context sources

  • Orbit is GitLab's derived, advisory graph (blast radius, dependency discovery) — query Orbit to discover, query GitLab directly to prove current state.
  • Work context (Beads/Gas City) defines what work exists; GitLab proves what code/CI/release state is real for that work.
  • Package registry facade failures (group-level vs project-level Composer/npm) are a GitLab capability-boundary concern — see the Failure Signature Catalog, not reinvented here.