Skip to main content

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.

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:

  • test[os:ubuntu,python:3.9]
  • test[os:ubuntu,python:3.10]
  • test[os:ubuntu,python:3.11]
  • test[os:macos,python:3.9]
  • test[os:macos,python:3.10]
  • test[os:macos,python: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.

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