Environments and variables
Configure each environment: variables, workers, how deploys run, and recipes.
1Open the environment
Deploy → Environments, then choose one, such as production or staging.
2Clone one
Project settings → Environments: name the new environment, pick one under Copy settings from and choose Clone. Its deploy settings, workers, recipes and variables come across, and its schedules come across switched off. Secret values are copied only if you tick Copy secret values too; otherwise you’re told which secrets to set. Connect a repository to a website for it to deploy.
3Variables
On the Variables tab, add environment variables and secrets. They’re encrypted, and previews never inherit them.
4From a password manager
Under Secrets from a password manager, connect Doppler (a service token for the config), 1Password Connect (your Connect server’s https address, a token, and the vault and item IDs; each field’s label becomes the variable name) or AWS Secrets Manager (a region, an access key that can read the secret, and its name; the secret’s value must be a JSON object). They sync every hour or when you choose Sync now, as secret variables for runtime and build. Variables set here by hand are never overwritten, and keys removed from the source are removed here.
5How deploys run
On the environment’s Settings tab, under How deploys run, choose the strategy (atomic, rolling, blue-green or canary). Approvals, deploy locks, weekly windows and freezes are on the Controls tab.
6Build server
On the Settings tab, under Build server, choose one of your app or worker servers and one of the project’s storage buckets. Deploys then clone, install dependencies and build there, and upload the built release to the bucket through a link that expires; the website’s server downloads it, unpacks it and runs the rest (environment file, migrations, going live). The bucket’s keys never reach either server, and each release is deleted from the bucket when its deploy finishes. The build server needs the same PHP and Node.js versions as the website’s. Docker and Compose deploys keep building on the website’s server.
7Build on GitHub Actions
For a server too small to build on, choose GitHub Actions under Build server on the Settings tab (PHP and Node.js environments with a GitHub repository). Copy the workflow shown into the repository at the path given (one per website, such as .github/workflows/buildpusher-shop.yml) and push it. It builds every push to the branch and uploads the result as the buildpusher artifact. Each deploy waits for that workflow’s run on its commit, then the website’s server downloads the artifact, unpacks it and runs the rest (environment file, migrations, going live). A failed run fails the deploy with a link to it. GitHub keeps each build for 7 days; redeploying an older commit runs the workflow again first. Variables the build itself needs go in the repository’s Actions secrets and variables.
8Destructive migrations
Tick Stop before destructive migrations on the environment’s Settings tab. Before migrating, a Laravel deploy lists the SQL its pending migrations would run (with migrate --pretend, which changes nothing) and stops if any of it drops, truncates or renames. The deploy page shows the statements; someone other than the person who deployed can approve them, and the same revision deploys again and migrates.
9Approve from Slack
On the environment’s Notifications tab, tick Needs approval for a Slack (or Teams) destination. Each deploy that needs approval arrives with Approve and Reject buttons; they open the deploy with that choice ready, so one more tap confirms it. Only people who can approve deploys, other than whoever started it, can confirm.
10Release analysis
On the Settings tab, under Watch health after each deploy, choose how long to watch, then the limits: failed requests, how much slower requests may get, and how far the Analytics conversion rate may drop. Each deploy is compared with the same length of time before it; past a limit, it’s marked failed and, with automatic rollback on, the previous release goes back live. The build page shows the before-and-after figures.
11Docker Compose
Choose the Docker Compose runtime on the Settings tab, give the Compose file (compose.yaml by default), the service that serves the website and its container port. Each deploy builds and starts the stack on your server as one project; the web service gets the website’s .env and sits behind Caddy with HTTPS, other services (a database, a worker) run beside it, and named volumes are kept between deploys.
12Resources
The Resources tab adds the databases, caches and other services the environment uses. A managed one is set up for you (MySQL uses the website’s database; Redis and Valkey run on the server); for an external one, enter its variables. Either way they go into .env.
13Workers and recipes
Run queue workers and schedulers from the Workers tab, and scripts on the environment’s servers from the Recipes tab.