Variables

Learn how to use environment variables in your pipelines.

Variables

Environment variables allow you to parameterize your pipeline configuration and pass values between stages.

Defining Variables

Pipeline Variables

Define variables at the pipeline level to make them available to all stages:

variables:
  NODE_ENV: production
  API_URL: https://api.example.com

stages:
  - name: build
    type: build
    config:
      buildArgs:
        NODE_ENV: $NODE_ENV
        API_URL: $API_URL

Stage Variables

Define variables for a specific stage:

stages:
  - name: test
    type: test
    config:
      image: node:18
      env:
        CI: 'true'
        TEST_TIMEOUT: '30000'
      commands:
        - npm test

Variable Types

Plain Text Variables

Standard environment variables visible in logs:

variables:
  LOG_LEVEL: debug
  MAX_RETRIES: '3'

Secret Variables

Secrets are encrypted and masked in logs:

secrets:
  DATABASE_URL:
    secretRef: db-connection-string
  API_KEY:
    secretRef: external-api-key

Note

Secrets are stored encrypted and decrypted only at runtime. They are masked in all logs and outputs.

Built-in Variables

Sluice provides several built-in variables:

Variable	Description	Example
`SLUICE_PIPELINE_ID`	Pipeline ID	`pipe_abc123`
`SLUICE_PIPELINE_NAME`	Pipeline name	`my-pipeline`
`SLUICE_RUN_ID`	Current run ID	`run_xyz789`
`SLUICE_VERSION`	Pipeline version	`5`
`SLUICE_STAGE_NAME`	Current stage name	`build`
`SLUICE_TRIGGER`	Trigger type	`webhook`

Git Variables

When triggered by a webhook:

Variable	Description	Example
`GIT_BRANCH`	Branch name	`main`
`GIT_COMMIT`	Full commit SHA	`abc123...`
`GIT_COMMIT_SHORT`	Short commit SHA	`abc123`
`GIT_TAG`	Tag name (if applicable)	`v1.0.0`
`GIT_AUTHOR`	Commit author	`[email protected]`
`GIT_MESSAGE`	Commit message	`Fix bug in...`

Variable Interpolation

Use variables in your configuration with different syntaxes:

Shell-style

config:
  image: $REGISTRY/$IMAGE_NAME
  tag: $VERSION

Template-style

config:
  image: '{{.Registry}}/{{.ImageName}}'
  tag: 'v{{.Version}}-{{.Commit}}'

Mixed

config:
  image: $REGISTRY/my-app
  tag: 'v{{.Version}}-$GIT_COMMIT_SHORT'

Variable Precedence

When the same variable is defined in multiple places, precedence is (highest to lowest):

Run overrides - Variables set when triggering a run
Stage variables - Variables defined in the stage config
Pipeline variables - Variables defined at the pipeline level
Built-in variables - Sluice-provided variables
Default values - Defaults specified in variable definitions

Default Values

Specify default values for optional variables:

variables:
  LOG_LEVEL:
    default: info
  REPLICAS:
    default: '2'

Conditional Variables

Set variables based on conditions:

variables:
  ENVIRONMENT:
    value: production
    condition: "branch == 'main'"
  ENVIRONMENT:
    value: staging
    condition: "branch == 'develop'"
  ENVIRONMENT:
    default: development

Passing Variables Between Stages

Use outputs to pass values from one stage to another:

stages:
  - name: build
    type: build
    config:
      # ...
    outputs:
      IMAGE_DIGEST: $DOCKER_IMAGE_DIGEST

  - name: deploy
    type: deploy
    config:
      image: my-app@$IMAGE_DIGEST

Warning

Outputs are only available to subsequent stages in the same run.

Best Practices

Use secrets for sensitive data - Never put passwords, API keys, or tokens in plain variables
Provide defaults - Define sensible defaults for optional variables
Use descriptive names - DATABASE_URL is clearer than DB
Document variables - Add comments explaining what each variable is for
Validate inputs - Check that required variables are set before using them

Next Steps

Pipeline Configuration - Full configuration reference
Webhooks - Set up automatic triggers