GitOps · Platform engineering · CI/CD · 7 min read ·
GitOps promotion without copying YAML between environments
Argo CD and Flux make deployments declarative; they do not by themselves solve promotion. How to move a change from dev to production with a record, a gate and no hand edits.
Teams adopt Argo CD or Flux, get a beautiful view of what is running, and then discover that "promote to staging" still means a person editing an image tag in a second file and hoping they copied it right. GitOps solved reconciliation. Promotion is a separate problem, and it deserves its own design.
What promotion has to guarantee
A promotion process is good enough when it can answer four questions without a human remembering:
- What exactly is being promoted (image digest, chart version, config revision)?
- From where did it come, and did it pass the previous stage?
- Who or what approved it, and against which policy?
- What is running in each environment right now, and since when?
Hand-edited YAML answers none of these reliably. A pull request answers some. A promotion controller answers all four.
The shapes that work
One repository, one directory per environment, promotion by pull request
The simplest honest approach. A pipeline opens a pull request that changes the image tag in envs/staging/, the merge is the approval, Argo CD reconciles it. It is auditable and it scales to a handful of services. It stops scaling when the number of services times the number of environments produces more pull requests than anyone reads, and when "what passed dev" is a fact in someone's head.
A promotion controller (Kargo or equivalent)
Kargo models freight (an immutable bundle of artifact versions) moving through stages (environments) subject to verification and approval. Promotion is a first-class object: it records what moved, when, why, and whether the stage's checks passed. Argo CD still does the reconciliation; Kargo decides what Argo CD should be reconciling in each stage.
This is the right shape once you have more than a few services or any requirement to show a promotion trail. It removes the hand edit entirely: the controller writes the change and Git records it.
Progressive delivery inside a stage
Promotion moves a version into an environment; progressive delivery controls how much traffic sees it. Argo Rollouts (or Flagger) runs a canary or blue/green with health analysis from your metrics, and rolls back on its own if the analysis fails. Use it in production and in any environment where a bad deploy has a cost.
Rules that keep it sane
- Promote digests, not tags.
:latestand mutable tags make "what is running" unanswerable. - Environments differ by values, not by copies. One chart, one base, per-environment overlays that are small enough to read.
- Verification is automated or it is skipped. Health checks, smoke tests and SLO queries that run as part of the promotion, not a checklist in a wiki.
- Production approval is a gate in the controller, not a Slack message. Record who approved and what they saw.
- Rollback is a promotion of the previous freight. Rehearse it.
Where to start
If you are on pull-request promotion and it still fits, add digests and automated verification first; that alone answers most of the four questions. If you are past the point where pull requests are read, introduce a promotion controller for one service, run it beside the old process for a month, and move the rest when the team trusts it.
We help teams design and adopt this as part of GitOps and platform engineering engagements, usually starting with a two-week review of the current delivery path.
Keep reading
Platform engineering · GitOps · CI/CD · 7 min
Golden paths that engineers actually take
A platform team's output is not the platform; it is the paths other teams take through it. How to build paved roads that are faster than the alternative, keep them honest with the people who use them, and avoid turning them into mandates.
CI/CD · Security · GitOps · 8 min
A pipeline that proves what it ships
Scanning, software bills of materials, signatures and admission control are four separate controls that only mean something together. How to build a delivery path where the cluster refuses anything the pipeline did not vouch for.
Kubernetes · Security · Platform engineering · 8 min
Isolating tenants on a shared Kubernetes cluster
A namespace is not a security boundary, but a namespace plus five other controls is a usable one. What separates tenants on a shared cluster, what still needs a cluster of its own, and how to decide which customer gets which.