Deploy scripts

What it is

Every site has a deploy script. It holds the commands your application needs between the code arriving and the release going live: installing dependencies, building assets, running migrations. It is written for you when the site is created, from a template for its runtime and the answers you gave on the creation form.

This is where you change what a deploy runs. If you want npm install instead of npm ci, open Deploy script in the site’s Settings and edit that line. The steps around it (fetching, the runtime install, the FPM pool, the Nginx vhost, the health-checked switch) are not editable. The same section lists them by name under What a deploy does, and the job log shows what each of them printed on the last deploy.

Where it runs

After the runtime toolchain is installed, and before the release is configured and activated. On PHP, Laravel, Node and static sites your script is the only thing that installs dependencies or builds assets. If a command is not in it, no deploy runs it.

It runs with bash, in the release directory, as the site's own Unix account. If it exits non-zero the deploy stops and the previous release keeps serving.

Commands resolve to this site's versions

php, composer, node, npm, npx, pnpm, yarn and bun resolve to the versions this site is pinned to, not to the server's defaults. composer install uses your PHP version even on a server running three of them. Changing the site's PHP version updates them.

Available variables

RELEASE_PATH   # the new release directory
APP_PATH       # the application directory, and the working directory
               # (the same as RELEASE_PATH unless the site deploys a subdirectory)
SHARED_PATH    # state that survives releases; shared/.env lives here
SITE_DOMAIN    # the site's primary domain
BRANCH         # the branch this release was built from

Example: a Laravel site

#!/usr/bin/env bash
set -euo pipefail

composer install --no-dev --prefer-dist --no-interaction --no-progress --optimize-autoloader

# Front-end assets, only when this repository has any.
if [ -f package.json ]; then
  npm ci

  npm run build
fi

php artisan migrate --force

php artisan config:cache
php artisan view:cache || true
php artisan route:cache || true
php artisan event:cache || true
php artisan storage:link || true

Reset to recommended puts this back. You can also empty the script, which is the right choice for a site with nothing to build. A deploy then fetches the code, configures the release, and activates it.

Extra scripts at other points

For work that does not belong with your build, a site can also run scripts at five named points: after-fetch, before-build, after-build, before-activate and after-activate. They run between the pipeline's own steps, never in place of one, and live behind Run something at another point in the same section.