Variable System¶

Overview¶

Variables are resolved values available in tasks via $ctx->get('name') and in templates via {{ name }}.

Resolution Priority (highest to lowest)¶

Resolution Order

Runtime overrides (-D NAME=value)
Dynamic variables
Context-specific constants
Global constants
Built-in: context = current context name

Secrets sit outside this order: a secret name may not collide with any other source, so there is nothing to resolve a priority against. They are resolved lazily, on first access.

Constants¶

variables:
    constants:
        dbHost: localhost
        dbName: myapp
        debug: false

Simple key-value pairs. Can be overridden per context.

Dynamic Variables¶

Computed at runtime when variables are first accessed. All dynamic variables are resolved at once and cached. If a dynamic variable fails to resolve (e.g. a command returns non-zero, or a git property is unavailable), it returns null.

type: command¶

userId:
    type: command
    command: "id -u"

Executes a shell command and returns trimmed stdout.

type: script¶

dockerImage:
    type: script
    script: '''
        if [ "$DEBUG" = true ]; then
            echo "dev-image"
        else
            echo "prod-image"
        fi
    '''

Executes a multi-line shell script. Use NEON triple-quotes (''') for multi-line values.

type: git¶

gitBranch:
    type: git
    property: branch

Property	Description
`branch`	Current branch name
`commit`	Full commit hash
`commitShort`	Short commit hash
`tag`	Current tag, if any

type: system¶

hostname:
    type: system
    property: hostname

Property	Description
`hostname`	System hostname
`user`	Current user
`os`	Operating system name
`phpVersion`	PHP version string
`cwd`	The project root Sputnik is working in -- the same directory `--working-dir` sets, not the shell's current directory
`timestamp`	Unix timestamp
`date`	Current date (YYYY-MM-DD)
`datetime`	Current date and time

type: env¶

home:
    type: env
    name: HOME

Reads an environment variable, or null if it is not set. For a value that must not be printed, declare it under secrets instead -- the same type works there and adds masking.

type: composite¶

buildInfo:
    type: composite
    providers:
        branch:
            type: git
            property: branch
        version:
            type: command
            command: "cat VERSION"

Returns an associative array with the result of each named provider.

Secrets¶

Variables that must never appear in output are declared under secrets instead of constants or dynamics:

variables:
    secrets:
        apiToken:
            type: command
            command: "pass show project/api"

Every value a secret takes is replaced with *** in everything Sputnik prints. See Secrets for the supported types, the resolution behaviour and the boundaries of what masking covers.

Context Overrides¶

contexts:
    prod:
        variables:
            constants:
                debug: false
                appEnv: prod

Context constants override global constants when that context is active.

Runtime Overrides¶

sputnik deploy -D DB_HOST=remote -D DEBUG=true

Highest priority. Override everything else.

Using Variables in Tasks¶

$dbHost = $ctx->get('dbHost');
$branch = $ctx->get('gitBranch');
$missing = $ctx->get('nonexistent', 'fallback');

Using Variables in Templates¶

DB_HOST={{ dbHost }}
GIT_BRANCH={{ gitBranch }}
OPTIONAL={{ missing | "default_value" }}