Jobs

Jobs are one-shot tasks that run to completion, such as database migrations, seed scripts, or batch processing. They share most configuration with services — including image, env, volumes, secrets, and service_account_name — but add controls for completion, retries, and cleanup.

Defining a Job

jobs:
  - name: db-migrate
    image_from_build: api-build
    command:
      - yarn
      - migrate

Like services, jobs use either image or image_from_build to specify the container image.

What's Different from Services

Jobs don't have ports or replicas. Instead, they have fields that control how the job runs and when it's cleaned up:

Restart Policy

Controls what happens when a job's pod exits:

jobs:
  - name: db-migrate
    image_from_build: api-build
    command:
      - yarn
      - migrate
    restart_policy: OnFailure

Options are OnFailure (retry on non-zero exit) and Never (don't retry the pod). Services always restart; jobs give you the choice.

Backoff Limit

Set the number of retries before the job is marked as failed:

jobs:
  - name: db-migrate
    image_from_build: api-build
    command:
      - yarn
      - migrate
    backoff_limit: 3

Parallelism and Completions

For batch workloads, control how many pods run concurrently and how many must succeed:

jobs:
  - name: batch-process
    image_from_build: worker-build
    command:
      - node
      - process.js
    parallelism: 4
    completions: 10

This runs up to 4 pods at a time until 10 total have completed successfully.

Suspend

Start a job in a suspended state. Useful when you want to define the job but trigger it later:

jobs:
  - name: manual-task
    image_from_build: api-build
    command:
      - node
      - one-off.js
    suspend: true

TTL and Completed Timeout

Control cleanup timing after a job finishes:

jobs:
  - name: db-migrate
    image_from_build: api-build
    command:
      - yarn
      - migrate
    ttl: 3600
    completed_timeout: 600

• ttl — seconds to retain the completed job before automatic cleanup
• completed_timeout — seconds the job is allowed to run after completion before cleanup

Common Patterns

Database Migrations

The most common use case — run migrations before services start:

builds:
  - name: api-build
    dockerfile: Dockerfile

jobs:
  - name: db-migrate
    image_from_build: api-build
    command:
      - yarn
      - migrate

services:
  - name: api
    image_from_build: api-build
    ports:
      - containerPort: 3000

Seed Scripts

Populate a database with initial data:

jobs:
  - name: db-seed
    image_from_build: api-build
    command:
      - yarn
      - seed
    restart_policy: Never

Schema Reference

See the Job schema for the full configuration reference.