Hooks

Deploy Hooks

You are an expert in extending Kamal deploys with hooks. Your goal is to run the right custom script at the right point in a deploy — pre-flight checks, build gates, deployment notifications, load-balancer draining — and to read the KAMAL_* environment variables Kamal passes in so those scripts know what is being deployed, by whom, and where.

Before You Start

Read what already exists before asking the user questions:

• .kamal/hooks/ — the default hooks folder. kamal init creates it with sample scripts. List it to see which hooks are already wired up.
• config/deploy.yml — check for a hooks_path (custom location) or hooks_output (output visibility) setting.
• .kamal/secrets — if a hook needs a token (for a webhook, an APM key), it is read from here.

How Hooks Work

Hooks let you run custom scripts at specific points during Kamal commands.

• Hooks live in the .kamal/hooks folder by default. Change the location with hooks_path (see Configuring Location and Output).
• The hook filename must be the hook name with no extension — for example pre-deploy, not pre-deploy.sh or pre-deploy.rb.
• If a hook script returns a non-zero exit code, the command is aborted. This is how a pre-deploy or pre-build hook gates a deploy.
• Kamal passes KAMAL_* environment variables into every hook so the script knows what is happening (see KAMAL_* Environment Variables).
• Skip all hooks for one command with --skip-hooks (see Skipping Hooks).

Running kamal init scaffolds the folder and drops in sample scripts you can edit or delete.

The Available Hooks

Each hook fires at a documented point. Name your script exactly as the hook name.

For the full detail on each hook — including the grouped-boot and rolling-reboot behaviors — see references/hook-reference.md.

Walk-Through: Add a Hook

Step 1 — Create the hook file

Put a script in .kamal/hooks named exactly after the hook, with no extension. For a pre-deploy gate:

# .kamal/hooks/pre-deploy

Give it a shebang and make it executable — Kamal runs the file directly:

chmod +x .kamal/hooks/pre-deploy

Step 2 — Write the script and exit non-zero to abort

A non-zero exit code aborts the command, so a pre-deploy or pre-build hook can stop a bad deploy before it starts:

#!/usr/bin/env bash
# .kamal/hooks/pre-build — refuse to build with uncommitted changes
if [ -n "$(git status --porcelain)" ]; then
  echo "Uncommitted changes present — commit before deploying." >&2
  exit 1
fi

Step 3 — Use the KAMAL_* variables

Kamal passes context in as environment variables. Read them to make the script aware of the version, performer, and target hosts:

#!/usr/bin/env bash
# .kamal/hooks/pre-deploy
echo "Deploying ${KAMAL_VERSION} to ${KAMAL_HOSTS} as ${KAMAL_PERFORMER}"

Step 4 — Deploy

Run your command as usual. The hooks fire at their points automatically:

kamal deploy

If you need to deploy without running any hooks this once, add --skip-hooks.

KAMAL_* Environment Variables

These variables are available to every hook command, intended for fine-grained audit reporting — triggering deployment reports or firing a JSON webhook:

The post-deploy hook additionally receives KAMAL_RUNTIME, set to the total seconds the deploy took.

Worked Example: A post-deploy Notification

The post-deploy hook runs after a deploy, redeploy, or rollback — a natural place to broadcast a deployment message or register the new version with an APM. This example posts a line to a preconfigured chatbot:

#!/usr/bin/env bash
# .kamal/hooks/post-deploy
curl -q -d content="[My App] ${KAMAL_PERFORMER} Rolled back to version ${KAMAL_VERSION}" https://3.basecamp.com/XXXXX/integrations/XXXXX/buckets/XXXXX/chats/XXXXX/lines

That posts a message like:

[My App] [dhh] Rolled back to version d264c4e92470ad1bd18590f04466787262f605de

Because post-deploy also gets KAMAL_RUNTIME, you can include the deploy duration in the message.

Configuring Location and Output

Both keys go in the root of config/deploy.yml.

hooks_path

Path to the hooks folder. Defaults to .kamal/hooks. Override it to keep hooks elsewhere:

hooks_path: /user_home/kamal/hooks

hooks_output

Controls hook output visibility. Set it globally or per-hook. CLI flags (-v, -q) override these settings.

With no setting, hook output follows the CLI verbosity flags. Failed hooks always show their output in the error message regardless of this setting.

Global setting for all hooks:

hooks_output: :verbose

Or per-hook:

hooks_output:
  pre-deploy: :verbose
  pre-build: :quiet

Skipping Hooks

Pass --skip-hooks (-H) to run a command without its hooks:

kamal deploy --skip-hooks

Use it when you need to bypass a gate for a one-off deploy. For how --skip-hooks fits into the deploy command's other flags, see the deploy skill.

Quick Reference

Related Skills

• deploy: For the full kamal deploy / kamal redeploy sequence these hooks fire within, and the other flags that pair with --skip-hooks.
• build: For the kamal build step where the pre-connect and pre-build hooks run.