Every deploy from Git runs a few steps before anything is published: install your dependencies, build your front end, and, if you ask for it, run your tests. We detect the first two from your project. Change them here when your project needs something else, or add a test command so a broken build never reaches your visitors.
Before you start
- Your site deploys from a Git repository (Deploy from Git). Build steps appears once one is connected.
- You need a role that can change the site's settings (Roles and permissions).
Set your build steps
- Open Sites → your site → Deploys, then Build steps (or Edit build steps in the side panel).
- Fill in the steps you want to change:
- Install: how dependencies are installed. Detected:
npm ci. - Build: how the front end is built. Detected: your
buildscript (orproduction/prod), orvite buildwhen Vite is installed and there is no script. - Tests: a command that must succeed, such as
npm test. Empty means no tests.
- Install: how dependencies are installed. Detected:
- To turn Install or Build off, type
skip. To go back to detection, empty the field. - Press Save build steps.
The side panel's Build box shows what is in use: your command, or detected (a step you turned off with skip also shows detected there). The new steps apply on your next deploy. Back to detected defaults empties all three commands at once.
Where the steps run
The steps run in a fresh build container that is used once and then deleted. It has Node.js, npm, PHP and Composer, and nothing else: your site's environment variables and secrets are not available there, so a build or test that needs them has to bring its own test settings. CI=true is set.
Install and Build run only when your repository has a package.json. Tests run whenever you have set a command.
After the build we publish the result to your site. There, a PHP project with a composer.json gets composer install --no-dev, and a Node.js app gets its production dependencies installed with the site's own Node.js version.
When the tests fail
If the Tests command exits with anything other than 0, the deploy stops before anything is uploaded. Your site is not updated, and visitors keep the version they had. The deploy shows as failed in Recent deploys, with the step that failed and its log under Log.
Database migrations
On a Laravel app (one with an artisan file), each deploy takes a copy of the database first, then runs php artisan migrate --force on the server. Untick Run database migrations after deploying to skip that step; the box is honoured on every deploy, for Laravel too.
Staging copy branch
With a staging copy turned on, set its branch under Staging copy. Pushes to that branch deploy to staging instead of the live site. Live site shows the branch the live site deploys, which is set by the repository you picked. Any other branch is ignored.
With the API or an assistant
PATCH /api/v1/sites/{slug}/build (deploy scope) and the set_build_steps tool take install_command, build_command, test_command, run_migrations, staging_branch and use_defaults. One difference from the portal: there is no skip, so the API cannot turn a step off. An empty command means detect it again, as in the portal.