Skip to main content

Deployment hooks

If you need something to run on every deploy, like code generation, deployment hooks run your own scripts as part of serverpod cloud deploy. Without them, those steps live in a separate command you remember to run yourself.

When to use hooks​

Hooks come in two shapes:

  • pre_deploy for anything that has to run before Cloud receives your project (regenerate Serverpod code, build a Flutter web client, compile non-Dart assets, run a test suite as a deploy gate).
  • post_deploy for anything that should fire after the upload completes (Slack notification, kick a downstream pipeline, mark a release in your tracker).

If your deploy doesn't depend on either, don't add hooks. Deploys work without them.

Configure hooks​

Hooks live in scloud.yaml under project.scripts. Each hook accepts either a single command (string) or a list of commands (array). See the scloud.yaml schema for the field types and validation rules.

Single command:

project:
  projectId: my-project
  scripts:
    pre_deploy: serverpod generate
    post_deploy: echo "Deployment complete"

Multiple commands run sequentially:

project:
  projectId: my-project
  scripts:
    pre_deploy:
      - serverpod generate
      - serverpod run flutter_build
    post_deploy:
      - curl -X POST https://hooks.slack.com/services/YOUR/WEBHOOK -d '{"text":"Deployed"}'

How scripts run​

Each command runs in your project directory (the one containing scloud.yaml) through the system shell (bash -c on macOS and Linux, cmd /c on Windows). Scripts inherit the environment variables of the shell that invoked serverpod cloud deploy, so CI-set secrets and your local PATH are available. Commands in an array run sequentially. Output streams to your terminal in real time as each one executes.

A non-zero exit code halts further commands in that hook.

warning

The pre_deploy and post_deploy hooks fail asymmetrically:

  • A failing pre_deploy script aborts the deploy before Cloud receives your code.
  • A post_deploy script runs after the upload, before Cloud finishes building and rolling out the new version. If it fails, the serverpod cloud deploy command exits with an error, but Cloud keeps deploying. Check the result with serverpod cloud status deployment show.

Plan your scripts accordingly: put anything that must succeed before your code ships in pre_deploy.