Job structure

Jobs are independent units of work within a workflow. They can run in parallel or sequentially based on dependencies.

Schema

See Schema Reference for the complete #Job definition.

Fields

name (optional)

The display name of the job.

Type: string

runner (optional)

Specifies the execution environment for the job. Can be any string identifier representing the runner. Runners are configurable Sandbox Engine templates that define the compute resources and environment for job execution.

Type: string

Default: None (uses default runner)

depends_on (optional)

A list of job IDs that must complete successfully before this job can run. Used to create sequential execution flows.

Type: list of strings

Default: None (job runs immediately if no dependencies)

note

When depending on a matrix job, this job waits for ALL matrix instances to complete successfully.

if (optional)

A condition controlling whether the job runs. It holds a boolean expression that is evaluated once the job's dependencies finish; if the expression is false, the job is skipped.

Type: string (a boolean expression) or bool

Default: None (the job runs when all depends_on jobs succeed)

Example:

jobs:
  deploy:
    depends_on: [train]
    # runs only if train succeeded (implicit) and inputs.deploy is 'true'
    if: inputs.deploy == 'true'
    steps:
      - name: Deploy to serving

See Job conditions for the expression syntax, the values you can reference (inputs, env, deps.<id>.state), and the failure() and always() functions.

matrix (optional)

Matrix configuration for parallel job execution. Creates multiple job instances with different variable combinations using Cartesian product.

Type: Matrix object (map of variable names to string arrays)

Example:

jobs:
  test:
    matrix:
      os: [ubuntu, macos]
      python: ["3.9", "3.10", "3.11"]
    steps:
      - name: Run tests
        env:
          OS: ${{ .matrix.os }}
          PYTHON: ${{ .matrix.python }}
        run: python -m pytest

This creates 6 job instances (2 OS × 3 Python versions), all running in parallel. Each instance gets a generated job ID of the form <job>-<value1>-<value2> (matrix values ordered by variable name, names dropped) and a display name of the form <name> (<value1>, <value2>). Since this job has no name, the display name falls back to the job ID:

Job ID	Display name
test-ubuntu-3.9	test (ubuntu, 3.9)
test-ubuntu-3.10	test (ubuntu, 3.10)
test-ubuntu-3.11	test (ubuntu, 3.11)
test-macos-3.9	test (macos, 3.9)
test-macos-3.10	test (macos, 3.10)
test-macos-3.11	test (macos, 3.11)

Matrix variables are accessed using ${{ .matrix.variable }} expressions.

See Matrix Jobs for detailed documentation.

working_dir (optional)

Default working directory for all steps in this job. Individual steps can override this with their own working_dir.

See Step Structure for details on working directory behavior and inheritance.

timeout (optional)

Maximum execution time for the entire job. If the job exceeds this duration, it will be terminated.

See Timeouts for detailed documentation on duration format and behavior.

env (optional)

Environment variables specific to this job. Available to all steps within the job.

See Environment Variables for details on scope and inheritance.

outputs (optional)

Named values the job exposes to jobs that depend on it. Each value is an expression over the job's own scope - its inputs, env, and the outputs of its steps (${{ .steps.<id>.outputs.<name> }}) - resolved when the job succeeds.

Type: map of output name to expression string

Example:

jobs:
  build:
    outputs:
      image: ${{ .steps.compile.outputs.image }}
    steps:
      - id: compile
        run: echo "image=myrepo/app:1.2.3" >> "$H2O_WORKFLOWS_OUTPUT"

A dependent job reads them as ${{ .deps.build.outputs.image }} in expressions, or deps.build.outputs.image in an if condition. An output name must start with a letter, contain only letters, digits, and underscores, not end with an underscore, and be at most 63 characters. Secrets cannot be referenced in an output value.

steps (optional)

An ordered list of steps to execute within the job. Steps run sequentially in the order defined.

Mutually exclusive with workflow - a job must have either steps or workflow, not both.

Type: list of Step objects

workflow (optional)

Call another workflow instead of executing steps. The called workflow must have trigger.callable: true.

Mutually exclusive with steps - a job must have either steps or workflow, not both.

Type: WorkflowCall object

See Reusable Workflows for detailed documentation.

Examples

Basic Job

jobs:
  train:
    name: Train Model
    steps:
      - name: Train model

Job with Dependencies

jobs:
  preprocess:
    name: Preprocess Data
    runner: cpu-large
    steps:
      - name: Clean and validate data

  train:
    name: Train Model
    depends_on: [preprocess]
    runner: gpu-large
    steps:
      - name: Train model

  deploy:
    name: Deploy Model
    depends_on: [train]
    runner: cpu-low
    steps:
      - name: Deploy to serving

---

Feedback

• Submit and view feedback for this page
• Send feedback about H2O Workflows to cloud-feedback@h2o.ai