Configuration

Templating & variables

Go templates + sprig in commands and scripts, plus the deploy context exported to the shell as $ENV vars - with the full variable table.

2 min read

cmds and inline scripts are Go templates (with sprig helpers), and the same values are exported to the shell as env vars - so write either {{.release_path}} (rendered by whoosh) or$RELEASE_PATH (expanded on the host).

Both forms work in cmds, inline scripts, file scripts, and ad-hoc run.

Value	Template	Env var
App name (`app.name`)	`{{.app_name}}`	`$APP_NAME`
Repo URL (`app.repo`)	`{{.repo}}`	`$REPO`
Branch (`app.branch`)	`{{.branch}}`	`$BRANCH`
Stage name	`{{.stage}}`	`$STAGE`
Deploy root (`app.deploy_to`)	`{{.deploy_to}}`	`$DEPLOY_TO`
Releases dir	`{{.releases_path}}`	`$RELEASES_PATH`
Shared dir	`{{.shared_path}}`	`$SHARED_PATH`
Git mirror	`{{.repo_path}}`	`$REPO_PATH`
Current symlink	`{{.current_path}}`	`$CURRENT_PATH`
This release dir	`{{.release_path}}`	`$RELEASE_PATH`
Release id (timestamp)	`{{.release_timestamp}}`	`$RELEASE_TIMESTAMP`
Deployed commit SHA	`{{.commit_hash}}`	`$COMMIT_HASH`
Releases kept per host (`app.keep_releases`)	`{{.keep_releases}}`	`$KEEP_RELEASES`
Target host the command runs on	`{{.host}}`	`$HOST`
Roles of that host (its full set)	`{{.roles}}` (list)	`$ROLES` (comma-joined)
Deploy phase a hook is running for	`{{.phase}}`	`$DEPLOY_PHASE`
Failure message (in a `deploy:failed` hook)	`{{.error}}`	`$DEPLOY_ERROR`

Plus:

Your vars - each key is a template value and an env var.
envs: entries (global and per-task) - exported as env vars.
{{.config}} (template only) - the whole resolved Deployfile keyed by its YAML field names: {{.config.app.name}}, {{range .config.hosts}}{{.address}} {{end}}.
The host table is printed by the whoosh <stage> deploy:hosts command (and auto-printed at the start of a deploy by the default print-inventory plugin). To iterate hosts in a template, use {{ range .config.hosts }}{{ .address }}{{ end }}.
{{.tasks.<name>}} (template only) - captured task state.
sprig functions - e.g. {{ env "CI_COMMIT_SHA" }}, {{ now | date "2006-01-02" }}.

Note

Template keys are lowercase, env names UPPERCASE. During a deploy, release_path/release_timestamp point at the new release and commit_hash is the SHA being deployed (resolved after deploy:updating). For a standalone task run they fall back to current_path, an empty timestamp, and an empty commit hash. phase/error are set only while a task runs as a hook.

Quote templated YAML values

A YAML value starting with { is read as a flow mapping, so name: {{ .x }} is a parse error. Always quote a leading template: name: "{{ .x }}".