How to Promote a Build Through Environments by Branch

Promotion by branch advances the exact commit from one environment branch to the next, so production runs the artifact staging already tested.

Environment promotion means moving a validated commit forward, not rebuilding it. Merge staging into production (or use a tag) so the deployed artifact is byte-for-byte what you tested. CI deploys on push to each environment branch.

Steps

• Deploy and validate on the staging branch.
• Promote by merging staging into production (fast-forward if possible).
• Deploy the same commit to production on push.
• Reuse the already-built artifact rather than rebuilding from source.

Promote and deploy

# Promote staging to production
git checkout production
git merge --ff-only staging
git push origin production

# production workflow reuses the prior artifact
# on: push: branches: [production]
#   - uses: actions/download-artifact@v4
#     with: { name: app-build }
#   - run: ./deploy.sh production

Gotchas

• Rebuilding at each stage can produce a different artifact; promote the built one.
• A non-fast-forward merge into production means the branches diverged; investigate before deploying.

Related guides