Skip to content

Infra Agent Law: GitLab First

This document defines the binding operational model for Infrastructure Agents within the Bluefly Factory. It establishes GitLab as the authoritative control plane for all infrastructure management.

1. The Core Principle: GitLab First

Use GitLab as the authoritative infrastructure management and evidence plane.

Before touching hosts directly, start with: * GitLab Projects & Source * Terraform Module Registry * Merge Requests & Pipelines (CI/CD Analytics) * GitLab Environments & Deployments * Runners (Group & Project Runner inventory) * Registries (Container, Package, Dependency Proxy) * Security (Vulnerabilities, Security Dashboard, Credentials, Policies, Compliance, Audit Events) * Observability (Logs, Metrics, Traces, Services, Hosts, Alerts, Exceptions) * Work (Work Items, Boards, Milestones, Roadmaps) * Kubernetes (GitLab Kubernetes Agent)

Direct SSH, docker ps, filesystem inspection, and raw host commands are diagnostic and readback mechanisms, not infrastructure authority and not the normal deployment workflow.

2. Unmanaged Drift

If a runtime exists but GitLab does not represent it, classify it as UNMANAGED_DRIFT, not as normal infrastructure. A container can absolutely exist on Oracle without GitLab knowing about it. That does not make GitLab wrong; it means the estate is out of governance.

3. The Required Execution Sequence

  1. GitLab first. Establish declared/managed state from projects, Terraform, MRs, pipelines, environments, runners, registries, packages, dependency data, security findings, audit events, cluster agents, and configured observability.
  2. Determine drift in GitLab terms (DECLARED, DEPLOYED, FAILED, MISSING, UNMANAGED, STALE, NOT_ESTABLISHED).
  3. Change through GitLab. Source branch → MR → CI/component → Terraform/Ansible/Fabric/deploy mechanism → environment/deployment record.
  4. Runtime readback after deployment. Oracle/NAS/Kubernetes direct inspection is proof and diagnosis, not the primary management path.
  5. Write the result back into GitLab evidence. Pipeline/deployment/environment/MR/WITNESS result must show what changed.

4. Specific Operational Rules

Deployments

Every deployment must terminate in: SOURCE_DECLARED=YES MR=MERGED CI=PASS RUNNER=IDENTIFIED ENVIRONMENT=RECORDED DEPLOYMENT=RECORDED EXPECTED_ARTIFACT=KNOWN RUNTIME_READBACK=PASS SECURITY_EVIDENCE=CHECKED WITNESS=PASS

  • Do not call a service deployed merely because a shell command succeeded.
  • Do not infer deployment state from containers when GitLab Environments/Deployments should own that lifecycle.
  • A deployment job must participate in GitLab's environment model using the environment: keyword in .gitlab-ci.yml. A job without a meaningful GitLab deployment/environment record is incomplete infrastructure plumbing.

Example standard for deployments: 

deploy:
  stage: deploy
  environment:
    name: staging
    url: https://stg.example.com
  script:
    - governed-deploy
    - governed-runtime-readback
Control chain: MR → pipeline → deployment job → GitLab Environment → runtime → readback → deployment evidence (Not: SSH → docker ps → "looks okay").

Runners

GitLab's runner inventory and runner/job tags are the scheduling authority. Runner tags are what GitLab uses to decide which runner can execute a job. * Do not infer runner state from host files when GitLab can provide runner state. * Host /etc/gitlab-runner/config.toml matters when diagnosing why a registered runner behaves incorrectly, but it should not be where you start deciding what runners exist.

Observability

  • GITLAB_OBSERVABILITY_CONFIGURED=YES → Inspect GitLab first.
  • GITLAB_OBSERVABILITY_CONFIGURED=NO → Absence in UI proves nothing. Diagnose the integration, and use runtime readback if required.

Kubernetes

  • Target architecture: GitLab project/group → GitLab Kubernetes Agent → authorized project/group access → CI/CD / operators / agents → cluster.
  • Do not use arbitrary long-lived kubeconfigs scattered across machines.

Manual Reconciliation

Do not manually reconcile infrastructure that belongs to Terraform, Ansible, GitLab Components, Fabric, or the GitLab Kubernetes Agent.

5. Architectural Boundaries

  • GitLab: Owns source custody, CI/CD, infrastructure delivery, security evidence, releases, packages, environments, deployment records, and operational surfaces.
  • Gas City: Owns agent work orchestration.
  • Beads: Own durable work.
  • Runtime (Oracle / NAS / cloud / cluster): Is the proof.

Control Plane Architecture: 

Thomas 
  ↓ 
BLU 
  ↓ 
Gas City / Mayor / Beads 
  ↓ 
Infra Agent 
  ↓ 
GitLab CONTROL PLANE 
  ├── source / MR 
  ├── CI/CD 
  ├── runners 
  ├── environments 
  ├── registries 
  ├── security 
  ├── observability 
  ├── Terraform 
  └── Kubernetes Agent 
  ↓ 
Oracle / NAS / cloud / cluster 
  ↓ 
runtime readback 
  ↓ 
WITNESS