Skip to main content

Expressions

Expressions enable dynamic values in workflow files. They allow you to reference workflow inputs, secrets, and environment 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 }}"

See Workflow Inputs for detailed documentation.

.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/b9c6e0da-355c-4683-bfbb-b7bf876e7b6b/secrets/ayiffo22n6gu  # Resource path in H2O Secure Store
    as: registry_token                                                          # Internal reference name

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

.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 }}"

.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

See Matrix Jobs for detailed documentation.

Where Expressions Work​

Expressions can be used in all string fields throughout the workflow, for example:

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

Type Coercion​

When inputs are referenced in expressions, they are automatically converted to strings. This allows inputs of different types to be used anywhere string values are expected.

String Inputs​

String inputs are used as-is without conversion:

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

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

Boolean Inputs​

Boolean values are converted 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 are converted 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 inputs are referenced in expressions.

Limitations​

Literal Expression Syntax

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

Workaround: Use shell string concatenation or alternative formatting:

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

Security Considerations​

⚠️ Command Injection Risk: User-provided inputs in expressions can contain malicious shell commands (e.g., 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