Skip to content

ADR-0016 — Next-Generation SSH-less Deployment Platform

  • Status: Proposed
  • Date: 2026-07-21
  • Related: ADR-0001, ADR-0014

Context

The platform currently utilizes a remote execution model (push-based) managed via GitLab CI and SSH to deploy to Oracle. This treats Oracle as a mutable "pet" server rather than a disposable runtime: * Source Code on Runtime: Oracle maintains Git checkouts, violating the principle of deploying artifacts. * Tribal Knowledge: Manual SSH interventions (git pull, docker compose restart) circumvent CI, causing configuration drift. * Missing Control Plane: Deployments bypass any centralized control plane, leaving GitLab CI as the sole entity trying to orchestrate runtime state over SSH. * Implicit Contracts: The deployment artifact is loosely defined as "whatever is in the Git repository," coupling the architecture tightly to Docker Compose.

Bluefly requires an Infrastructure-as-Code platform where Oracle can be destroyed and reprovisioned automatically without any manual Git or Docker operations, governed by strict separation of concerns.

Decision

We establish a Desired State Model utilizing Release Bundles as the immutable contract, severing the direct tie between CI (GitLab) and Runtime (Oracle).

  1. Ownership Boundary Separation:
  2. GitLab: Owns source control, continuous integration (builds, tests), and artifact packaging.
  3. Bluefly (Control Plane): Owns business intent and the Desired State graph (Application → Capability → Pack → Deployment → Environment → Release Bundle). Bluefly records what should run, not how to run it.
  4. Gas City (Execution Plane): Owns the reconciliation loop (Deployment Controller). It discovers the desired state, compares it with actual state, and executes deployment mechanics.

  5. Oracle (Runtime): Owns compute execution and persistent storage. Runs workloads agnostically with zero deployment logic.

  6. The Release Bundle Contract: Applications must deploy Release Bundles, not source code. A Release Bundle is a platform-agnostic artifact containing:

  7. metadata.yaml (App, version, deployment ID, signatures)
  8. runtime/ (e.g., compose.yaml, kubernetes/)
  9. images.yaml (Exact immutable OCI SHAs)

  10. packs.yaml, migrations/, healthchecks/, sbom/, provenance/, rollback.yaml

  11. Deployment State Machine: Every deployment strictly transitions through: Draft → Built → Verified → Published (CI boundary) → Desired (Bluefly) → Reconciling → Running → Verified → Superseded → Archived.

  12. Target Lifecycle: Developer → Git Repository → GitLab CI → Release Bundle → Bluefly (Desired State) → Gas City (Reconciler) → Oracle Runtime

Rule

  1. Deployments MUST NOT execute via SSH pushes from CI.
  2. Oracle MUST NOT maintain Git checkouts of application source code or raw Compose files.
  3. Applications MUST output a Release Bundle artifact; they MUST NOT dictate deployment mechanics to the runtime.
  4. Gas City MUST be the sole executor of deployment reconciliation on Oracle.
  5. All deployment states MUST be governed by the Bluefly Object Graph.

Consequences

  • What becomes true: The platform achieves true immutability at the runtime layer. Oracle becomes entirely disposable. Deployments are deterministic, versioned, and easily reversible via Bluefly state changes.
  • What is now blocked: Ad-hoc git pull or docker compose up on Oracle is strictly prohibited and physically impossible without bypassing the Gas City controller.
  • Migration notes:
  • gitlab_components must be updated to output Release Bundles instead of executing SSH commands.
  • The Gas City Deployment Controller must be provisioned onto Oracle via IaC to begin pulling and reconciling Release Bundles.
  • Legacy SSH deployments will run in parallel until the controller fully assumes authority for an application.