Skip to main content

Expressions

Expressions enable dynamic values in workflow files. Use expressions to reference workflow inputs, secrets, environment variables, and matrix variables throughout your workflow configuration.

Syntax​

${{ .context.field }}

Available contexts​

.inputs - Workflow input references​

Access workflow inputs defined at the workflow level.

Format: ${{ .inputs.<input_name> }}

The <input_name> is the key from the workflow's inputs definition.

Example:

inputs:
  model_type:
    type: string
    required: true
  epochs:
    type: string
    default: "100"

jobs:
  train:
    env:
      MODEL_TYPE: "${{ .inputs.model_type }}"
      EPOCHS: "${{ .inputs.epochs }}"

For more details, see Inputs.

.secrets - Secret references​

Access secrets defined at the workflow level.

Format: ${{ .secrets.<reference_name> }}

The <reference_name> is the as field from the secret definition.

Example:

secrets:
  - name: workspaces/abc123/secrets/xyz789  # Resource path in H2O Secure Store
    as: registry_token                       # Internal reference name

jobs:
  deploy:
    env:
      REGISTRY_TOKEN: "${{ .secrets.registry_token }}"  # Use the reference name

For more details, see Secrets.

.env - Environment variable references​

Access environment variables defined at workflow, job, or parent step levels.

Format: ${{ .env.VARIABLE_NAME }}

Example:

env:
  DATA_API: https://data.example.com
  EXPERIMENT: baseline-v1

jobs:
  train:
    env:
      DATASET_URL: "${{ .env.DATA_API }}/datasets"
      RUN_NAME: "Training ${{ .env.EXPERIMENT }}"

For more details, see Environment variables.

.matrix - Matrix variable references​

Access matrix variables defined at the job level.

Format: ${{ .matrix.<variable_name> }}

Availability: Only available within jobs that define a matrix field.

Example:

jobs:
  train:
    matrix:
      algorithm: [xgboost, lightgbm, random_forest]
      max_depth: ["5", "10", "15"]
    steps:
      - name: Train model
        env:
          ALGORITHM: ${{ .matrix.algorithm }}
          MAX_DEPTH: ${{ .matrix.max_depth }}
        run: python train.py --algorithm $ALGORITHM --max-depth $MAX_DEPTH

For more details, see Matrix jobs.

Where expressions work​

You can use expressions in all string fields throughout the workflow, including:

  • Environment variable values (env)
  • Shell commands (run)
  • Upload and download paths (upload.path, upload.destination, download.source, download.path)
  • Working directories (working_dir)
  • Concurrency group identifiers (concurrency.group)
  • Job and step names
  • Workflow call inputs

Type coercion​

When you reference inputs in expressions, they automatically convert to strings. This allows inputs of different types to work anywhere string values are expected.

String inputs​

String inputs pass through without conversion:

inputs:
  model_type:
    type: string
    default: "xgboost"

env:
  MODEL: ${{ .inputs.model_type }}  # Result: "xgboost"

Boolean inputs​

Boolean values convert to lowercase string literals "true" or "false":

inputs:
  debug_mode:
    type: bool
    default: false

env:
  DEBUG: ${{ .inputs.debug_mode }}  # Result: "false"

steps:
  - run: |
      if [ "$DEBUG" = "true" ]; then
        echo "Debug mode enabled"
      fi

Integer inputs​

Integer values convert to decimal string representation:

inputs:
  max_retries:
    type: int
    default: 3

env:
  RETRIES: ${{ .inputs.max_retries }}  # Result: "3"

steps:
  - run: python script.py --retries $RETRIES
Note

All expression values are strings. The coercion happens automatically when you reference inputs in expressions.

Limitations​

Literal expression syntax​

There is no escape mechanism for literal ${{ strings. If you need to output the literal text ${{ .inputs.foo }}, the system evaluates it as an expression.

Workaround: Use shell string concatenation or alternative formatting:

run: echo 'Use $''{{ .inputs.name }} to reference inputs'

Security considerations​

warning

Command injection risk: User-provided inputs in expressions can contain malicious shell commands (for example, xgboost; rm -rf /).

Best practices​

  1. Use environment variables instead of direct interpolation in shell commands:

    steps:
      - name: Train model
        env:
          MODEL_TYPE: "${{ .inputs.model_type }}"
        run: python train.py --model "$MODEL_TYPE"

  2. Validate and sanitize inputs before they reach workflows.

  3. Quote shell variables to prevent word splitting.

  4. Avoid expressions in sensitive fields like file paths when using untrusted inputs.

Feedback