Promoting staging to production

Promotion takes a release you tested on one project, usually staging, and ships that exact commit to another, usually production.

A normal deploy builds whatever the branch holds at the moment you press the button. That isn't necessarily what anyone tested: someone may have merged in between, and then production gets code staging never ran. Promotion names the commit, so what you ship is what you checked.

Setting it up#

You need two projects that deploy the same repository:

1. A staging project, with Environment set to Staging. It usually deploys a branch like develop or staging, often automatically on every push (see auto-deploy).
2. A production project, with Environment set to Production, deployed at least once so CloudPilot knows which server it runs on.

The two can be on the same server or on different ones. Repository addresses are compared by repository, not by spelling, so https://github.com/acme/shop and git@github.com:acme/shop.git count as the same one.

Promoting#

1. Deploy staging and check it.
2. On the Projects page, click the promote button (↑) on the production project.
3. Pick the release. Staging's newest release is selected; older ones are listed too, each with its commit and message.
4. Read the checks (below), then click Promote.

Progress, the log and the result then appear in the project's deploy window, just like a normal deploy.

What is checked first#

What production gets#

• The same commit. The server checks that commit out, and refuses to build anything else. CloudPilot then confirms which commit the server actually built. If it's not the one promoted, the deployment is marked failed, not successful.
• Production's own environment variables. Staging's are never copied over.
• A fresh build on production's server. The build runs from the same commit with the same lockfile, so dependencies install the same way. The built files aren't copied between servers.
• A safety net. The previous production release stays on disk. If the promoted release fails its health check, CloudPilot switches back to the previous release automatically. You can also roll back by hand at any time.

If staging's branch was force-pushed after the release, the commit is fetched by name. If the commit no longer exists at all, the promotion fails and nothing changes.

History#

Deployments show the commit they built. Promotions are marked Promoted and rollbacks Rollback, so after an incident you can see exactly which code was live and when.

Protected projects#

On a protected production project, a promotion needs someone else's approval, just like a deploy. The approver sees the commit and the project it came from. Approving builds the release that was requested, even if staging has moved on since.

Who can promote#

Promoting needs project.deploy, the same permission as deploying, plus access to production's server. Every promotion is recorded in the audit log with its commit, source and target.

Requirements#

Both servers need an up-to-date agent: staging's to record commits, and production's to build a specific commit. If production's agent is too old, the promotion fails with a message saying so, and nothing on the server changes.