Skip to main content

Workflow structure

The workflow is the top-level definition that contains all jobs and their configurations. This page describes the fields available at the workflow level.

Fields​

id (required)​

Unique identifier for the workflow. This ID forms part of the resource name: /workspaces/{workspace-id}/workflows/{id}.

Type: string (non-empty)

Use the id when calling this workflow from other workflows with WorkflowCall. The ID must be unique within the workspace.

Example:

id: model-training-pipeline
Note

For workflow references and resource names, see Reusable workflows.

name (optional)​

Display name of the workflow.

Type: string

The name field is optional and does not need to be unique. Multiple workflows can share the same display name. Use name for human-readable display only. WorkflowCall references always use the id field.

Example:

id: model-training-pipeline
name: Model Training Pipeline

inputs (optional)​

Workflow input parameters that you provide when triggering the workflow. Reference inputs using ${{ .inputs.<name> }}.

Type: Map of input definitions

For input definition, types, defaults, and usage, see Inputs.

concurrency (optional)​

Controls concurrent execution of workflows. Use this field to prevent multiple workflow instances from running simultaneously.

Type: Concurrency object

Example:

concurrency:
  group: model-deploy
  cancel_in_progress: false

For detailed configuration, see Concurrency.

trigger (optional)​

Defines when the workflow runs, such as on a schedule with cron expressions, and whether other workflows can call it.

Type: Trigger object

For scheduling options, see Triggers. For callable workflows, see Reusable workflows.

env (optional)​

Global environment variables available to all jobs and steps in the workflow.

Type: Map of string to string

For scope, inheritance, and precedence rules, see Environment variables.

secrets (optional)​

Secrets from H2O Secure Store. Define secrets at the workflow level and reference them using ${{ .secrets.<as> }}.

Type: List of secret definitions

For secret definition, resource paths, and usage, see Secrets.

cancel_on_failure (optional)​

Cancel all running jobs when any job fails.

Type: bool

Default: true

For behavior details and interaction with continue_on_error, see Failure handling.

jobs (required)​

Map of job definitions, keyed by unique job ID. Each job contains steps that run sequentially.

Type: Map of job definitions

For job configuration, runners, dependencies, and execution order, see Jobs.

Complete example​

The following example shows a workflow with multiple configuration options:

id: ml-training-pipeline
name: ML Training Pipeline

inputs:
  model_type:
    type: string
    required: true
    description: Type of model to train
  epochs:
    type: int
    default: 100

concurrency:
  group: training-${{ .inputs.model_type }}

trigger:
  schedule:
    - cron: "0 0 * * *"
      inputs:
        model_type: "xgboost"

env:
  EXPERIMENT_NAME: baseline-v1

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

cancel_on_failure: true

jobs:
  train:
    name: Train Model
    steps:
      - name: Train
        env:
          MODEL: ${{ .inputs.model_type }}
          API_KEY: ${{ .secrets.api_key }}
        run: python train.py --model $MODEL --epochs ${{ .inputs.epochs }}
Feedback