Skip to content

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:

  1. What exactly is being promoted (image digest, chart version, config revision)?
  2. From where did it come, and did it pass the previous stage?
  3. Who or what approved it, and against which policy?
  4. 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. :latest and 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.