Skip to main content

Environment variables

Environment variables allow you to configure workflows, jobs, and steps with key-value pairs. Define them at the workflow, job, or step level. Environment variable values support expressions, allowing you to reference secrets and other environment variables.

Format​

Environment variables use a YAML map format:

env:
  MODEL_REGISTRY: models
  DATA_PATH: /datasets
  EPOCHS: "100"
warning

All values must be strings. Quote numbers and booleans. Never put sensitive data directly in environment variables. Use secrets instead.

Scope levels​

You can configure environment variables at three different levels, each with different scope and inheritance behavior.

Workflow-level environment variables​

Environment variables defined at the workflow level are available to all jobs and steps within the workflow.

Location: Top-level env field in the workflow

Use case: Global configuration values used across multiple jobs

Example:

id: model-training-pipeline

env:
  EXPERIMENT_NAME: baseline-v1
  DATA_PATH: /datasets
  MODEL_REGISTRY: models

jobs:
  # All jobs can access EXPERIMENT_NAME, DATA_PATH, and MODEL_REGISTRY
  train:
    name: Train Model
    steps:
      - name: Train model
        run: python train.py

Job-level environment variables​

Environment variables defined at the job level are available to that specific job and its steps.

Location: env field within a job definition

Use case: Job-specific configuration values

Example:

jobs:
  train:
    name: Train Model
    env:
      MODEL_TYPE: xgboost
      LEARNING_RATE: "0.001"
      BATCH_SIZE: "32"
    steps:
      - name: Train model
        run: python train.py

Step-level environment variables​

Environment variables defined at the step level are available only to that specific step.

Location: env field within a step definition

Use case: Step-specific configuration

Example:

steps:
  - name: Train model
    env:
      EPOCHS: "100"
      EARLY_STOPPING: "true"
    run: python train.py

Scope and inheritance​

Environment variables at different levels merge together, with more specific levels taking precedence.

Inheritance order:

  1. Workflow env vars are available to all jobs and steps
  2. Job env vars are added to workflow env vars for that job (overriding workflow values for the same keys)
  3. Step env vars are added to workflow and job env vars for that step (overriding job and workflow values for the same keys)

Precedence: Step > Job > Workflow

Example​

env:
  EPOCHS: "50"           # Workflow level
  DATA_PATH: /datasets

jobs:
  train:
    name: Train Model
    env:
      EPOCHS: "100"      # Overrides workflow EPOCHS for this job
      BATCH_SIZE: "32"   # Adds new variable
    steps:
      - name: Train baseline
        # This step has: EPOCHS=100, DATA_PATH=/datasets, BATCH_SIZE=32
        run: python train.py

      - name: Train advanced
        env:
          EPOCHS: "200"  # Overrides job EPOCHS for this step
        # This step has: EPOCHS=200, DATA_PATH=/datasets, BATCH_SIZE=32
        run: python train.py --advanced

Combining with secrets​

Environment variables work alongside secrets to provide the complete runtime environment. Define secrets at the workflow level and reference them in environment variables using expressions.

  • env: For static values and expressions that reference secrets
  • secrets: Define sensitive data from H2O Secure Store (workflow-level only)
secrets:
  - name: workspaces/abc123/secrets/xyz789
    as: registry_token

jobs:
  deploy:
    name: Deploy Model
    env:
      MODEL_NAME: baseline-xgboost
      VERSION: "1.0"
      REGISTRY_TOKEN: "${{ .secrets.registry_token }}"  # Reference secret via expression
    steps:
      - name: Deploy model
        run: |
          # This step has access to:
          # - MODEL_NAME and VERSION (static values)
          # - REGISTRY_TOKEN (secret value via expression)
          python deploy.py --model ${MODEL_NAME} --token ${REGISTRY_TOKEN}
Note

Secrets are always defined at the workflow level and referenced using ${{ .secrets.<name> }} expressions.

Complete example​

id: ml-pipeline
name: ML Training Pipeline

env:
  EXPERIMENT: baseline
  LOG_LEVEL: info

secrets:
  - name: workspaces/abc123/secrets/api-key
    as: api_key

jobs:
  preprocess:
    env:
      INPUT_PATH: /data/raw
      OUTPUT_PATH: /data/processed
    steps:
      - name: Preprocess data
        run: python preprocess.py --input $INPUT_PATH --output $OUTPUT_PATH

  train:
    depends_on: [preprocess]
    env:
      MODEL_TYPE: xgboost
      API_KEY: "${{ .secrets.api_key }}"
    steps:
      - name: Train model
        env:
          EPOCHS: "100"
        run: python train.py --model $MODEL_TYPE --epochs $EPOCHS

      - name: Validate model
        env:
          EPOCHS: "10"  # Override for validation
        run: python validate.py --epochs $EPOCHS
Feedback