🪜 Multi-Environment Promotion for Infrastructure as Code

The phrase “but it worked in staging” is usually a lie — not a deliberate one, but a structural one. It worked in staging because staging and production were configured differently, and the difference was exactly the thing that broke. Multi-environment promotion is the discipline that makes that sentence true instead of a punchline.

After enough late-night promotions gone wrong, I’ve landed on a small set of principles that hold across any IaC tool. Here they are, with the AI assists that make them less tedious.

The core idea: same code, different inputs

The whole game is this: every environment runs the identical infrastructure code, parameterized by per-environment inputs. Dev, staging, and prod differ only in variables — instance sizes, counts, endpoints, feature flags — never in the logic.

The anti-pattern is copy-pasted environments: a dev/ directory and a prod/ directory with duplicated, slightly-diverged code. The moment they diverge, staging stops predicting production, and your promotion guarantees evaporate.

infra/
├── modules/            # the actual logic — shared, identical
└── environments/
    ├── dev.tfvars      # small, cheap, permissive
    ├── staging.tfvars  # prod-shaped, smaller
    └── prod.tfvars     # the real thing

One body of code, three input files. That’s the structure that makes promotion meaningful.

Make staging actually resemble production

A staging environment that’s a tenth the size, with different networking and a stubbed dependency, tests almost nothing useful. The closer staging mirrors prod in shape — same topology, same managed services, same network boundaries — the more a successful staging deploy predicts a successful prod deploy.

You can scale down quantity (fewer nodes, smaller instances) without losing fidelity. What you can’t change without losing the guarantee is kind: same database engine, same load balancer type, same ingress path. AI is handy for auditing this — paste both tfvars/config files and ask “what structural (not size) differences exist between staging and prod, and which could cause a deploy to succeed in staging but fail in prod?”

Promotion means moving an artifact, not re-running code

Here’s a distinction that trips teams up. Promotion should move a known-good artifact forward, not re-execute source against each environment and hope it produces the same thing.

For image-based infra, that’s literally promoting an image (the AMI/container you tested in staging is the one that goes to prod). For declarative IaC, the equivalent is promoting a specific git commit / plan that already passed the lower environment, rather than letting prod build from a moving main.

The principle: the thing that reaches prod is the thing you already validated lower down, byte-for-byte where possible. No rebuild, no “it’ll probably be the same.”

The promotion pipeline

A promotion flow that works in practice:

1. Change merges to the main branch after review and the cheap test layers pass.
2. Auto-deploy to dev. Fast, low-stakes, frequent. Breakage here is free.
3. Promote to staging — same artifact/commit, staging inputs. Run integration tests against it.
4. Gate to prod. A human approval, plus the full policy and test suite, plus a plan review.
5. Deploy to prod with the same artifact, prod inputs, and a watched rollout.

# CI: promotion is parameterized, not duplicated
deploy:
  parameters: [env]
  script:
    - apply --var-file=environments/${env}.tfvars --commit=${VALIDATED_SHA}

Notice the same deploy job serves every environment — only the inputs change. That’s the structural guarantee in code form.

Review the prod plan before it runs

The single highest-value gate is a human reviewing the plan for prod — the precise diff of what’s about to change — before approving. This is where AI shines as a reviewer:

“Here’s the prod plan diff. Flag anything destructive (deletes, replacements, in-place changes that cause downtime), and tell me which changes weren’t present in the staging plan we already approved.”

That last clause is the magic. If a change is about to hit prod that didn’t appear in staging, something is wrong — divergent inputs, drift, or a race. Catching that pre-apply is worth more than any post-mortem. I keep promotion-review prompts for exactly this gate.

Handle the data and stateful resources carefully

Stateless infra promotes cleanly. Databases, queues, and persistent volumes don’t — you can’t blue/green a database the way you can a web tier. For stateful resources:

• Decouple schema migrations from infra promotion. Run migrations as their own gated step, backward-compatible, so a rollback of the infra doesn’t strand the data.
• Never let promotion delete-and-recreate a stateful resource. This is the catastrophic mistake — a config change that triggers a replace on a database. Policy-as-code can hard-block this; make it a rule.

Roll back like you mean it

Promotion that can’t roll back isn’t a pipeline, it’s a one-way street. Because every environment runs the same code from a known commit, rollback is “promote the previous known-good commit/artifact” — the exact same mechanism, in reverse. Test that path before you need it. The first time you roll back should not be during an incident.

Where AI fits across promotion

• Environment diff audits — structural drift between env configs.
• Plan review — flagging destructive and unexpected changes pre-apply. The biggest win.
• Generating the parameterized pipeline from a description of your environments.
• Migration safety review — “is this schema change backward-compatible enough to survive an infra rollback?”

What AI won’t do is own the approval. The human gate before prod exists because someone accountable should look at the diff and say yes. AI makes that yes better-informed; it doesn’t replace it.

Start here

If your environments are copy-pasted today, the migration is worth it:

1. Extract shared logic into modules/roles; reduce environments to input files.
2. Make staging prod-shaped (scale down quantity, not kind).
3. Promote validated artifacts/commits, not re-runs.
4. Add a prod plan-review gate with AI-assisted diff triage.
5. Decouple and protect stateful resources.
6. Rehearse rollback before you need it.

Do this and “it worked in staging” becomes a reliable prediction instead of an excuse. Keep your review prompts in a prompt library and let the structure do the heavy lifting.