SaaS & data, an interactive architecture walkthrough
CI/CD pipeline: how the architecture works
How a CI/CD pipeline builds and tests each commit on ephemeral runners, signs artifacts, and rolls out to production in metric-checked canary steps.
This is a learning explainer based on public engineering writing and general design practice. It is simplified, it is not the actual architecture of any company, and it may be inaccurate.
Interactive diagram
Overview
A CI/CD pipeline turns every commit into tested, signed artifacts and moves them safely into production. On each push, a CI controller reads the pipeline definition stored with the code and fans independent jobs out to ephemeral runners, which build, test and scan the change in parallel using shared dependency caches.
Publishing uses short-lived credentials issued per job instead of stored cloud keys, and each image is signed with a record of the commit and pipeline that built it. Delivery is GitOps-style: the pipeline commits the new image version to a deploy config repository, a controller in each cluster pulls and applies it, and production rollouts shift traffic in steps while checking error rate and latency, rolling back automatically on regressions. This is a simplified learning design, not any specific product's implementation.
Trade-offs and what changes at scale
Ephemeral runners and per-job credentials are safer but slower to start than long-lived build machines, which caching partly offsets. Pull-based deployment keeps production credentials out of CI at the cost of a short sync delay. Canary analysis catches regressions that tests miss but needs reliable metrics and enough traffic to compare. At larger scale build time dominates, so remote caching, test selection based on what changed and sharding become the main levers, and runner capacity is autoscaled with queue length.
How it works, step by step
The walkthrough above, as text. Each step lights up the components named under it.
A developer pushes to a branch, the Git Host sends a webhook, and the CI Controller reads the pipeline file at that commit and records a run in the Pipeline DB. The pipeline is versioned with the code, so a branch can change its own build.
Independent jobs such as build, lint and test shards go onto the Job Queue at once and run in parallel on Ephemeral Runners. A fresh runner per job means no state leaks from one build to the next.
Runners restore dependency and image-layer caches from the Build Cache using keys derived from lockfile hashes. Cache scope is limited by branch, so a pull request cannot overwrite the main branch's cache with something malicious.
Ephemeral Runners check out the commit, build it and run the tests, streaming logs and test reports to the Log Store. Splitting slow test suites across shards keeps feedback within minutes.
Security Scanners check dependencies for known vulnerabilities, the diff for leaked secrets and the image for vulnerable packages. Findings above a severity threshold fail the pipeline before anything is published.
To publish, the job exchanges its identity token with Workload Identity for credentials that last only as long as the job and only for this repository and branch. No long-lived cloud keys are stored in CI.
The image is pushed to the Artifact Registry by digest and signed by the Provenance Signer with a record of which commit and pipeline built it. Clusters can then refuse images that were not built by this pipeline.
On the main branch, the last job commits the new image digest to the Deploy Config Repo. Deployments become ordinary commits that can be reviewed, audited and reverted.
The GitOps Controller sees the change, applies it to the Staging Cluster and reports any difference between the repo and what is running. Clusters pull their desired state, so CI never needs credentials to production.
For production, the Rollout Controller shifts traffic to the new version in steps such as 5%, 25%, 50% and 100%. Most bad releases are caught while they serve a small share of users.
At each step the controller queries the Metrics Provider for error rate and latency of the new version, and rolls back automatically if they are worse than the stable one. A bad deploy is reverted even when nobody is watching a dashboard.
The Notifier reports each job's status back to the pull request and to team chat. Branch rules on the Git Host block merging until required checks pass.
Sequence diagram
The same walkthrough as a UML sequence diagram, one lane per layer or group (19 components in all), left to right in the order a request reaches them, numbered by step. A loop on a lane is a step that stays inside that group. Solid arrows are synchronous calls, dashed are asynchronous.
Key components
Continuous Integrationdomain
- Build Cache: dependency and layer caches (s3)
- CI Controller: turns events into pipeline runs
- Ephemeral Runners: fresh VM or container per job
- Job Queue: jobs waiting for a runner (redis)
- Log Store: job logs and test reports (s3)
- Pipeline DB: runs, jobs, status, history (postgresql)
- Security Scanners: dependencies, secrets, image CVEs
Sourcelayer
- Developer: pushes commits, opens PRs
- Git Host: repos, PRs, webhooks, branch rules
Artifacts & Trustdomain
- Artifact Registry: container images by digest
- Provenance Signer: signs images with build provenance
- Workload Identity: short-lived cloud credentials per job
Continuous Deliverydomain
- Deploy Config Repo: desired image versions per environment
- GitOps Controller: syncs clusters to the config repo
- Metrics Provider: error rate and latency for analysis
- Production Cluster: live traffic
- Rollout Controller: canary steps and automatic rollback
- Staging Cluster: pre-production environment
Notifier
- Notifier: status checks, chat messages
Sources
Public writing this explainer draws on. Read these for what the real systems actually do.
- GitHub docs: Dependency caching (keys, restore keys, branch scope, no secrets)
- GitHub docs: OpenID Connect in Actions (short-lived cloud credentials)
- moby/buildkit: concurrent, cached builds with registry cache export
- Argo CD docs: Overview (Git as desired state, sync, rollback)
- argoproj/argo-rollouts: canary and blue-green with metric analysis
Make it yours
Copy this diagram and its walkthrough into your own workspace, then change anything: swap Postgres for DynamoDB, add a cache, rewrite the narration. Free, and it uses no AI credits.
Related walkthroughs
- Multi-tenant SaaS analytics pipelineHow a SaaS product collects events from many customers, keeps each tenant's data isolated, and serves fast dashboards from a columnar store.
- Metrics and monitoring systemHow a monitoring system scrapes metrics from every service, alerts through grouped and routed notifications, and keeps years of data in object storage.
- Log aggregation pipelineHow a log pipeline collects lines from every host, buffers them in a topic, indexes only labels, and keeps compressed text in object storage.
This is a learning explainer based on public engineering writing and general design practice. It is simplified, it is not the actual architecture of any company, and it may be inaccurate. Real systems differ in the details. Browse the library.