Skip to content
Tutorials Center
My learning

Topics

Lesson 10 of 37 ยท GitOps Principles

Environments and Promotion in GitOps: Dev, Staging, Production

Promote a release through dev, staging and production with GitOps: pull-request promotion, image tag updates from CI, per-environment overrides, approval gates and safe rollback.

A release does not jump straight into production. It moves through environments: development, staging (or QA), then production. In GitOps, "promoting" a version means changing a file in Git so that the next environment's desired state references it. Argo CD does the rest. This lesson shows patterns for that file change, who or what should make it, and how to keep environments honest.

Everything here is read-only YAML or conceptual. The runnable blocks are stand-ins: a promotion pipeline model and a drift report between environments. They do not call Git or Argo CD.

What differs between environments?

Most of an application is identical everywhere: the Deployment shape, the Service, the probes. A few things differ:

  • the image version (dev runs newer builds than production),
  • replica counts and resource requests,
  • hostnames and configuration values (database URLs, feature flags),
  • secrets (different credentials per environment),
  • the target cluster and namespace.

With Kustomize, the shared part is a base and each environment is an overlay. With Helm, the shared part is the chart and each environment has its own values file. Either way the difference is small, explicit and reviewable.

YAML
# apps/shop/overlays/production/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  - ../../base
images:
  - name: registry.example.com/shop/web
    newTag: 1.8.2
replicas:
  - name: web
    count: 6

Promotion to production is a pull request that changes newTag: 1.8.1 to 1.8.2 in this file.

Promotion patterns

Ways to promote

Bot commits CI writes the dev tag
Pull request Humans approve prod
Promotion job Copy tag dev to staging

Combine them: automate lower, gate higher.

1 / 2
  1. Automatic to dev. After CI builds web:1.8.2, a bot commits that tag to overlays/dev. Argo CD syncs it automatically.
  2. Promotion to staging. A scheduled job or a manual workflow copies the tag from dev to staging once dev has been healthy for some time.
  3. Promotion to production. A pull request updates the production overlay; the CODEOWNERS group reviews it; merging triggers the sync (manual or automated).

Tools can help: some teams use scripts or workflow runners, the Argo CD Image Updater (writes new tags back to Git or sets them on the Application), Kargo (a separate promotion tool from the Argo creators), or Renovate/Dependabot opening PRs for tag bumps. The core idea stays the same: promotion is a Git change.

flowchart LR
  CI["CI builds web:1.8.2"] -->|"bot commit"| Dev["overlays/dev"]
  Dev -->|"auto-sync, tests pass"| Stg["overlays/staging (PR or job)"]
  Stg -->|"pull request + approval"| Prod["overlays/production"]

Each arrow is a commit; each box is a folder on the same branch.

Stand-in: a promotion pipeline

This model keeps the version of each environment, refuses to promote a version that has not been healthy in the previous stage and prints the result.

JS Stand-in: promotion pipeline

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Stand-in: environment drift report

Environments are supposed to differ only on purpose. This second stand-in lists differences between two environments so a reviewer can tell intentional ones (replicas, host) from accidental ones (a feature flag that exists only in staging).

JS Stand-in: compare environments

Press Run (or Ctrl + Enter) to see the console output here.

No output.

image is flagged for review because a version difference is only legitimate while a promotion is in flight. FEATURE_X exists only in staging, which might be a forgotten flag.

Rollback

To roll back, revert the promotion commit (or set the previous tag) and merge. Argo CD's own rollback button and argocd app rollback also exist, but they only work when automated sync is disabled and are temporary: the next sync from Git will reapply the newer version. In GitOps, the durable rollback is a Git revert.

Preview environments

Pull requests can get temporary environments. An ApplicationSet with a pull request generator creates an Application per open PR and removes it on close (Multi-cluster and ApplicationSets covers it). These are short-lived, so branches are acceptable there.

Good practices

  • Promote the same artifact, never rebuild per environment. Immutable tags or digests guarantee staging and production run identical bits.
  • Keep environment differences in a small number of clearly named files.
  • Make production sync deliberate: manual or protected by a sync window, while dev auto-syncs.
  • Record why in the commit or PR description; it is your change log.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. In GitOps, what is promotion?

    Promotion is a Git change; Argo CD reconciles the target environment to it.
  2. 2. Why promote the same image artifact through all environments?

    Rebuilding per environment can change the result; promoting one immutable artifact avoids that.
  3. 3. Which is the durable way to roll back production in GitOps?

    UI rollbacks are temporary; Git remains the source of truth, so the fix belongs in Git.
  4. 4. What usually differs between a base and an environment overlay?

    Overlays keep only the small environment-specific differences.

Summary

  • Promotion means committing a version change for the next environment.
  • Use base plus overlays (Kustomize) or values files (Helm) so differences stay small.
  • Automate lower environments, gate production with pull requests and CODEOWNERS.
  • Promote one immutable artifact; do not rebuild per environment.
  • Roll back by reverting in Git; UI rollbacks are temporary.

Next: The Application Manifest