Skip to main content

Jobs

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

Fields​

name (optional)​

Display name of the job.

Type: string

Example:

jobs:
  train:
    name: Train Model

runner (optional)​

Specifies the execution environment for the job. Runners are configurable Sandbox Engine templates that define compute resources and environment settings.

Type: string

Default: Uses the default runner if not specified.

Example:

jobs:
  train:
    runner: gpu-large

depends_on (optional)​

List of job IDs that must complete successfully before this job runs. Use this field to create sequential execution flows.

Type: List of strings

Default: The job runs immediately if no dependencies are specified.

Example:

jobs:
  preprocess:
    steps:
      - run: python preprocess.py

  train:
    depends_on: [preprocess]
    steps:
      - run: python train.py
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: 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 configuration 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]

Access matrix variables using ${{ .matrix.variable }} expressions. For detailed documentation, see Matrix jobs.

working_dir (optional)​

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

Type: string

For details on working directory behavior and inheritance, see Steps.

timeout (optional)​

Maximum execution time for the entire job. If the job exceeds this duration, the system terminates it.

Type: Duration string (for example, "1h30m", "45m")

For detailed documentation on duration format and behavior, see Timeouts.

env (optional)​

Environment variables specific to this job. These variables are available to all steps within the job.

Type: Map of string to string

For details on scope and inheritance, see Environment variables.

steps (optional)​

Ordered list of steps to execute within the job. Steps run sequentially in the order you define them.

Type: List of step objects

This field is mutually exclusive with workflow. A job must have either steps or workflow, not both.

For step configuration, see Steps.

workflow (optional)​

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

Type: WorkflowCall object

This field is mutually exclusive with steps. A job must have either steps or workflow, not both.

For detailed documentation, see Reusable workflows.

Examples​

Basic job​

jobs:
  train:
    name: Train Model
    steps:
      - name: Train model
        run: python train.py

Job with dependencies​

jobs:
  preprocess:
    name: Preprocess Data
    runner: cpu-large
    steps:
      - name: Clean and validate data
        run: python preprocess.py

  train:
    name: Train Model
    depends_on: [preprocess]
    runner: gpu-large
    steps:
      - name: Train model
        run: python train.py

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

Job with timeout and environment variables​

jobs:
  long-running-task:
    name: Long Running Task
    timeout: "4h"
    env:
      LOG_LEVEL: debug
      MAX_RETRIES: "3"
    steps:
      - name: Execute task
        run: python long_task.py
Feedback