Hooks

Hooks run your own commands at fixed points of a deploy. For example: generate a key before the build, reload a systemd unit on the server, or tell a game server to save its world before its container is replaced.

Declare them in dockflow.yml under hooks:, one list per phase.

A first exampleCopy Anchor Link

version: 1
app: shop
hooks:
  before_build:
    - name: generate keys
      script: scripts/generate-keys.sh
      secrets: [JWT_PRIVATE_KEY]
  before_deploy:
    - name: back up the world
      service: game
      exec: ["rcon-cli", "save-all"]
      timeout: 10m
      fatal: false
    - host: sudo systemctl daemon-reload
  after_deploy:
    - name: tell the chat
      run: 'curl -fsS -X POST -d "deployed $DOCKFLOW_VERSION" "$CHAT_WEBHOOK"'
      secrets: [CHAT_WEBHOOK]
  after_failure:
    - run: echo "deploy of $DOCKFLOW_VERSION failed" >&2
environments:
  production: {}

Each entry has exactly one kind (run, script, host or exec) and runs in order within its phase. A phase stops at the first fatal hook that fails.

PhasesCopy Anchor Link

hooks: can also be set inside an environment. There, it replaces the top-level hooks: for that environment.

KindsCopy Anchor Link

• exec takes an argument list, not a shell string. Write exec: ["sh", "-c", "…"] when you need a shell inside the container.
• exec hooks can only be used from before_deploy on. Before that, nothing of the new release runs.
• A host hook's command is sent to sh -s on the server's standard input, with its environment exported at the top of that script. No value appears in a command line on the server.
• A host hook runs without a terminal: a sudo call needs a rule that allows it without a password.

OptionsCopy Anchor Link

dockflow validate checks the shape of each entry. It does not check that a script file exists, that an exec hook's service is in the Compose file, or that listed secrets have values. Those errors appear when the hook is about to run. A missing secret stops the run with exit code 3, before anything happens.

When each kind runsCopy Anchor Link

exec hooks run inside the agent, on the server. Local and host hooks run in the CLI, before the agent starts or after it finishes, never in the middle of the agent's run. This way the agent can finish a deploy even if the CLI's connection drops. Why: see ADR-0022.

If the agent's run fails, the agent rolls back, runs the after_failure exec hooks, and reports the failure. The CLI then runs the after_failure local and host hooks.

after_failure does not run:

• when the run stops on the CLI's side before the agent starts (a failed build, a fatal before_* local or host hook, a missing secret);
• when another run holds the lock.

Commands that run hooksCopy Anchor Link

• dockflow deploy runs every phase.
• dockflow build --push, and dockflow build with build.builder: remote, run the before_build and after_build hooks. --skip-hooks turns them off.
• A local dockflow build without --push runs no hooks. Neither do dockflow plan, dockflow rollback and the day-2 commands.

Environment variablesCopy Anchor Link

Every hook gets these environment variables:

• the built-in variables: DOCKFLOW_APP, DOCKFLOW_ENV, DOCKFLOW_STACK, DOCKFLOW_VERSION, DOCKFLOW_GIT_SHA, DOCKFLOW_GIT_BRANCH, DOCKFLOW_SERVER (see environment variables);
• the environment's vars;
• the secrets listed in the hook's secrets:, by their unprefixed name (JWT_PRIVATE_KEY, read from PRODUCTION_JWT_PRIVATE_KEY for production). Other secrets are not passed.

Local hooks also inherit part of the CLI's environment, what a shell and the usual tools need:

• PATH, HOME, USER, LOGNAME, SHELL, TERM, COLORTERM, NO_COLOR, TZ, LANG, LANGUAGE and LC_*, TMPDIR, TMP, TEMP, the XDG_*_HOME and XDG_RUNTIME_DIR directories;
• SSH_AUTH_SOCK, the proxies (HTTP_PROXY, HTTPS_PROXY, NO_PROXY, ALL_PROXY, in either case), and the local Docker's DOCKER_HOST, DOCKER_CONTEXT, DOCKER_CONFIG, DOCKER_CERT_PATH, DOCKER_TLS_VERIFY;
• on Windows, the system's own (SYSTEMROOT, COMSPEC, PATHEXT, USERPROFILE, APPDATA, …);
• the CI's description of the run: CI, GITHUB_*, RUNNER_*, CI_*, GITLAB_*, BUILDKITE_*, BITBUCKET_*, and Jenkins' BUILD_ID, BUILD_NUMBER, BUILD_URL, JOB_NAME, BRANCH_NAME, TAG_NAME, GIT_COMMIT, GIT_BRANCH, WORKSPACE, JENKINS_URL. A name holding TOKEN, SECRET, PASSWORD, PASSWD, JWT, KEY, CREDENTIAL or AUTH is left out (GITHUB_TOKEN, CI_JOB_TOKEN), and so is CI_REPOSITORY_URL, which holds GitLab's job token.

Nothing else is inherited: not the variables of any environment's secrets (PRODUCTION_*, STAGING_*, even when one of them would match a family above), nor DOCKFLOW_SECRETS, DOCKFLOW_SSH_KEY*, SOPS_AGE_KEY*, or a token your CI sets (NPM_TOKEN, AWS_*). A hook that needs one of these values lists it under secrets:, which reads it from PRODUCTION_NPM_TOKEN, DOCKFLOW_SECRETS or .env.dockflow, as any secret.

host hooks get the variables above on top of the SSH session's own environment, and exec hooks on top of the container's.

$ in hook commandsCopy Anchor Link

Hook commands (run, host, exec) are neither interpolated nor rendered as templates. $NAME reaches the shell as you wrote it, and the shell expands it from the environment the hook gets.

A script: that needs a real template must be listed under templates:. It then runs rendered, from a temporary copy made when the hook starts, so it sees what earlier hooks wrote. Your project's file is not modified.

# dockflow.yml (fragment)
templates:
  - scripts/notify.sh
hooks:
  after_deploy:
    - script: scripts/notify.sh   # runs with {{ DOCKFLOW_VERSION }} and the vars rendered

# dockflow.yml (fragment)
hooks:
  after_deploy:
    - run: echo "$DOCKFLOW_ENV is now on $DOCKFLOW_VERSION"   # the shell expands these

Output and maskingCopy Anchor Link

Each line a hook prints becomes a hook.log event, between hook.started and hook.finished (with the exit code). The terminal shows these lines prefixed with the hook's name; --json prints them as events.

Before any line is shown or stored, every value of the environment's secrets is replaced with ***, whether the hook lists that secret or not. The masking works on exact values: a secret that a hook transforms (base64-encodes, splits) is not recognised.

Failures and exit codesCopy Anchor Link

A hook fails when it exits with a non-zero code, cannot start, or runs past its timeout. A non-fatal failure is shown as a warning, and the run goes on. A fatal failure does this:

after_build hooks are not fatal unless you set fatal: true. See exit codes for the full list.