Catalog My learning Blog
CI/CD and DevOps Tutorial: Build a Delivery Pipeline · Phase 3 · Lesson 20 · 3 min read

Environment Promotion: Dev, Staging, Production

On this page
  1. What environment promotion means
  2. Dev, preview, staging and production
  3. Per-environment config with Kustomize overlays
  4. Promotion as a pull request
  5. Common environment promotion mistakes
  6. Check yourself

What environment promotion means

Environments exist so you can find problems before users do. That only works if what you test is what you ship. The rule from Day 5 applies at every step: the artifact never changes between environments; only configuration does.

Dev, preview, staging and production

EnvironmentPurposeDataWho deploys
Local / devFast iterationFake or seededDevelopers, any time
Preview (per pull request)Review a change in isolationSeededCI, automatically
StagingFinal check in a production-like setupProduction-like, anonymizedCI after merge
ProductionReal usersRealPromotion from staging

The closer staging is to production (same infrastructure code, same versions, similar data volume), the more its green light means. Differences between them are where "worked in staging" incidents come from.

One artifact moves from dev to staging to production, picking up each environment's configuration but never being rebuilt.
One artifact moves from dev to staging to production, picking up each environment's configuration but never being rebuilt.

Per-environment config with Kustomize overlays

Following the twelve-factor app approach, anything that varies by environment lives outside the image: URLs, feature settings, log levels, scaling, and secrets (from a secrets manager, Day 11). With Kustomize, a shared base plus one small overlay per environment:

YAML
# overlays/production/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
namespace: checkout-production
resources:
  - ../../base
images:
  - name: ghcr.io/acme/checkout-svc
    newTag: 3f9a1c2b7d4e      # the same tag in every environment once promoted
replicas:
  - name: checkout-svc
    count: 6
configMapGenerator:
  - name: checkout-config
    literals:
      - LOG_LEVEL=info
      - PAYMENTS_URL=https://payments.example.com

The staging overlay is the same shape with its own values. Comparing the rendered output of both proves what differs:

Code
diff <(kustomize build overlays/staging) <(kustomize build overlays/production)
Code
<   LOG_LEVEL: debug
<   PAYMENTS_URL: https://payments.sandbox.example.com
>   LOG_LEVEL: info
>   PAYMENTS_URL: https://payments.example.com
<   namespace: checkout-staging
>   namespace: checkout-production
<   replicas: 2
>   replicas: 6

(ConfigMap name hashes also differ, which is how Kustomize triggers a rollout when config changes.) The image line doesn't appear in the diff because it's identical. Both renders validate with kubeconform. Helm values files per environment achieve the same thing.

Promotion as a pull request

With GitOps (Day 18), promotion is a change to the production overlay's newTag, ideally opened automatically after staging checks pass:

  1. Merge to main builds 3f9a1c2b7d4e and updates the staging tag.
  2. Automated tests and a soak period run against staging.
  3. A bot opens a pull request setting production to the same tag. Approving it is the release decision (continuous delivery), or it merges automatically (continuous deployment, Day 4).

Tools like Kargo and Argo CD Image Updater automate these promotion steps.

Common environment promotion mistakes

  • Environment-specific builds (npm run build:prod) bake config into the artifact, so staging tests a different build. Read config at startup instead.
  • Long-lived environment branches (staging, production branches that drift) instead of one main with overlays.
  • Manual hotfixes in production that never reach staging or Git.
  • A shared staging that's always broken by someone's half-finished work; preview environments per pull request reduce the contention.

Check yourself

Only configuration: endpoints, scaling, log levels, feature flags and secrets. The artifact must be identical, so whatever staging verified is exactly what reaches production.

It produces a different artifact per environment, with different settings baked in at build time, so what staging tested isn't what production runs. Inject environment-specific configuration at runtime instead.

A pull request that sets the production overlay's image tag or digest to the version already verified in staging. Review and merge it, and the agent rolls it out, leaving an audit trail of every promotion.

A short-lived environment per pull request lets reviewers and product owners try changes before merging. Automate creation and cleanup to control cost.

Differences in data size, software versions, configuration or network setup let bugs pass staging and surface only in production. The closer staging is, the more its test results actually tell you.