Architecture One-Pager

CI/CD Platform · Solution Architecture v1.0 · Amazon Web Services · Platform Architecture · 2026-09

Tenant code executes only inside single-use, hardware-isolated sandboxes that hold no long-lived credential and cannot write shared state; every trusted act — brokering a secret, signing provenance, deciding a gate, recording an outcome — happens in a control plane that never executes tenant code.

An engineer pushes a commit, switches to Slack, and ninety seconds later a green check appears next to their pull request. That check is the most-used piece of software in their working day and the one they think about least. Behind it, a stranger's code — because a pull request from a fork is a stranger's code — has just been compiled, tested and thrown away on the company's own machines, and a signed statement now exists saying which commit produced which container image. The problem this platform solves is not making builds fast. It is that the convenient way to build this system and the safe way differ by one boundary, and almost every widely-used CI system has shipped a variant of the same bug: tenant code was allowed to touch something the platform needed to trust. A fork build reads the instance metadata endpoint and leaves with a deployment credential. A cache entry written by that fork build is restored, an hour later, into the build that produces the production image. The second problem is downstream of the first: without a non-forgeable link between commit, build and deployed artefact, the question "what is running in production and which source produced it" is answered by archaeology rather than by query.

Classify every run at admission as trusted or untrusted from the event itself, and carry that classification, immutable, for the run's whole life. Execute every job in a sandbox created for that job and destroyed after it, with hardware-level isolation between concurrent jobs and no long-lived credential inside any of them. Keep the cache readable by everything and writable only by trusted runs. Put the signing key, the secret broker, the gate decision service and the run state machine in a control plane that never executes tenant code, so provenance records what the platform observed rather than what a build claimed. Seal each artefact by content digest with a signed attestation in an append-only log. Then promote that same digest through environments, binding configuration at deployment, so what reached production is byte-identical to what passed staging, and rollback is a pointer move rather than a rebuild.

What it is, and what it is not

• One sandbox per job, destroyed after it — not A pool of reused containers with a cleanup step
• Provenance signed by the control plane from what it observed — not A build that signs a statement about itself
• A trust class assigned once, at admission, from the event — not A permission the pipeline can declare or escalate
• A cache read by everything and written by trusted runs only — not A shared cache that everyone contributes to
• One artefact digest promoted through every environment — not A rebuild per environment from the same commit
• Gates decided outside the pipeline that they govern — not Gate jobs inside the pipeline the author controls
• Platform failure and user failure as distinct outcomes — not A red build whose cause the engineer has to guess

The decisions that are the architecture

1. Every sandbox is single-use, and that is a security decision rather than a hygiene one (ADR-01) — A sandbox is created for one job and destroyed after it. Reuse is the cheapest performance win available in a CI platform and the costliest security decision available, because a residue is not a bug you find in testing. The platform buys cold-start engineering and a warm pool instead, and accepts the cost-per-job-minute that follows.
2. Isolation is hardware-level, and it does not vary by trust class (ADR-02) — Jobs run in microVMs on nested-virtualisation-capable hosts, not in hardened containers, because only virtualisation answers "a build rooted the kernel". A trusted branch build is contained exactly as strictly as a fork build, because a compromised dependency inside a trusted build is indistinguishable from a hostile fork — and that is now the more likely attack.
3. Trust is a property of the run, assigned at admission, derived from the event (ADR-03) — The classification is computed once from the trigger, before any capacity is committed, stored as a column on the run, and cannot be raised by anything the pipeline declares or by anything that happens later. A trust class that can be escalated mid-run is not a boundary.
4. The cache is read wide and written narrow (ADR-04) — Any run may read the cache; only a trusted run may write it, and every entry is integrity-verified on restore with a failure treated as a miss. A cache writable by an untrusted run is a code-execution path into every trusted build that reads it afterwards, and the measurably slower fork build is the accepted price.
5. Provenance asserts what the platform observed, never what the build claimed (ADR-06) — The signing key lives in the control plane and is never present inside a sandbox. The job reports its outcome; the attestor signs from the inputs the platform recorded. A compromised build can therefore produce a bad artefact but not a credible claim about one, which is the difference between an attestation worth verifying and a decoration.
6. Credentials are minted per job and revoked when the job ends (ADR-07) — Every credential a job holds is short-lived, scoped to that job's tenant, repository, ref and trust class, and revoked at job end rather than left to expire. Identity federation therefore sits on the hot path of every job instead of being a configuration detail, and a leaked token's useful life is the job's life.
7. Fairness is decided in the scheduler, not asked for politely (ADR-09) — Per-tenant concurrency entitlements with weighted fair queuing and lending of idle capacity, so a 900-job monorepo pipeline cannot push a five-job pipeline behind it. Queue wait inside an entitlement is an SLO; a tenant over its entitlement has no wait guarantee. Without this, the platform's fairness story is an email asking large teams to be considerate.
8. The runner's report is evidence, not truth; the lease is truth (ADR-13) — Runner loss is detected by lease expiry rather than by silence, and a job is never reported successful on the basis of an absent runner. A network partition therefore resolves to re-dispatch, never to a false green, and retry happens only for platform failure with the cause recorded.
9. Build once, promote the bits (ADR-15) — One artefact digest crosses every environment with configuration bound at deployment time. That is the only design in which "did we ship what we tested" has a cryptographic answer rather than a procedural one, and it is what makes rollback a five-minute pointer move instead of a twenty-minute rebuild.
10. Gates are decided outside the pipeline they govern (ADR-16) — A decision service consulted by the deployer, not gate jobs inside the pipeline, because a pipeline author must not be able to weaken the gates that apply to their own deployment. Production fails closed when the service is unavailable, overrides are recorded with actor, reason and expiry, and their usage count is a watched signal.

Why this should still be right in ten years

Hypervisors, queue technologies, signing formats and the registries this platform talks to will all be replaced inside its life. These are the properties that should outlast them.

• The boundary is not a technology. "The control plane never executes tenant code" is a statement about where code runs, not about which hypervisor runs it. Firecracker, gVisor, a successor nobody has built yet, or dedicated hardware can each satisfy it, and every decision downstream — where the signing key lives, why the runner's report is validated, why the cache splits into two privileges — survives the substitution unchanged.
• Attacks move towards the supply chain, not away from it. The industry trend through the 2020s was steadily away from "the attacker compromises your server" and towards "the attacker compromises something your build trusts". Every year that trend continues makes the isolation-plus-attestation posture more obviously correct and the reused-container posture less defensible. The design is aligned with the direction of travel rather than with the current threat list.
• Content addressing outlives the store. An artefact identified by the digest of its bytes is identifiable in any store, by any tool, for as long as the hash function holds. Tags, environments and registries are pointers into that space and are cheap to move. A platform that identified artefacts by its own allocated ids would have to migrate identity every time it migrated storage.
• Separating platform failure from user failure is a cultural invariant. The infrastructure-failure ratio is not an AWS metric or a Kubernetes metric. It is the number that decides whether engineers read a red build or reflexively retry it, and it will matter identically on whatever substrate the platform runs in 2036. Designing the outcome taxonomy to make it measurable is a permanent asset.
• Fairness pressure only increases. Monorepos get larger, generated code gets more voluminous, and AI-assisted development raises pushes per engineer per day. Every one of those trends increases the ratio between the largest tenant's burst and the smallest tenant's pipeline, which is exactly the ratio weighted fair queuing exists to bound. A global-FIFO design degrades monotonically as the estate grows.
• The costs are the ones that get cheaper. The price of this architecture is cold-start latency and cost per job-minute on isolated compute. Both are properties of the substrate, and both have improved by roughly an order of magnitude over the last decade. The price of the alternative — an unprovable artefact in production — does not get cheaper with hardware.

Non-functional targets

Every figure below is a stated assumption for this design, chosen to be defensible and arguable rather than measured. A reviewer who changes one can follow it to the decision that depends on it.

Scope

In scope

• Repository-hosted pipeline definitions, DAG compilation, schema and policy admission, and an immutable effective-definition record per run
• Trust classification of every run at admission, and the credential, cache and publish postures that follow from it
• A durable queue with per-tenant entitlements, priority tiers and visible queue position
• Single-use, hardware-isolated sandbox execution with mediated egress, streaming logs and a six-outcome taxonomy
• A content-addressed artefact store, a read-wide write-privileged cache, and a dependency mirror
• Control-plane-signed provenance and SBOM per artefact in an append-only transparency log
• Environment registry, ordered promotion by digest, deployment locks, rollback, and a gate decision service outside the pipeline
• Run observability: live tail, first-failure summary, flake detection, delivery metrics and cost per run

Explicitly out of scope

• The source-control system itself — the platform consumes its events and API and writes back only a check status
• The public package and container registries a build pulls from; they are proxied and cached, not hosted
• The runtime platform that receives a deployment, and its own configuration stores
• Test authoring, test frameworks and test infrastructure inside a job
• Incident management, on-call routing and the postmortem process
• Developer laptops and any local build cache on them
• Progressive delivery, remote build execution and test impact analysis, all named and deferred to Phase 3

What a four-week prototype should prove

The prototype's job is to falsify the central claim — that a fork build can run usefully on the same substrate as a trusted build without ever touching anything the platform needs to trust — on two repositories and one environment, not to build a platform.

1. One repository, two pipelines: a trusted branch build and a fork pull-request build, on one microVM host with a warm pool of ten
2. Measure queued-to-first-step at p50 and p95 with a cold pool and a warm pool, and publish the cost per job-minute of both
3. Implement the trust classifier and prove, by attempting it, that a fork build cannot obtain a secret, a cache write credential or a publish identity
4. Implement the attestor with a signing key the sandbox provably cannot reach, and verify an attestation from outside the platform using only the transparency log
5. Promote one digest through two environments with configuration bound at deployment, then roll back and measure it
6. Implement the six-outcome taxonomy and the lease, and measure the infrastructure-failure ratio over 500 deliberately-disrupted jobs

• A fork build reads the instance metadata endpoint: it receives nothing usable, the attempt is logged against the run, and the maintainer sees why
• A fork build writes a poisoned cache entry: the write is refused by credential, not by validation, and no trusted build is affected
• The host is killed mid-job: the lease expires, the job is re-dispatched with attempt 2 and cause recorded, the partial log survives, and no green check appears
• The gate decision service is stopped: promotion to production is refused with a named reason, and promotion to test proceeds under fail-open policy
• A signed attestation is edited in place: external verification against the transparency log fails, and the artefact is quarantined rather than deleted
• Two promotions to the same environment are issued a second apart: the deployment lock serialises them and the audit trail shows both, in order

Open risks, carried rather than hidden

The reasoning behind every component and technology choice is in the Architecture Decision Record: 17 records across 6 areas, each with the alternatives that lost and what the choice costs.