Jobs

A job is an ordered sequence of tasks. Jobs let you compose existing tasks into workflows — like a CI pipeline, a deployment sequence, or a full onboarding setup — without duplicating commands.

Basic job

version: v1

tasks:
  lint:
    cmds: [npm run lint]
  test:
    cmds: [npm test]
  build:
    cmds: [npm run build]

jobs:
  ci:
    description: "Full CI pipeline"
    tasks:
      - lint
      - test
      - build

Run it:

meriadoc run job ci
# or shorter:
meriadoc job ci

Tasks run sequentially in the order listed. If any task fails, the job stops (unless on_failure.continue is true).

Shared environment variables

Env vars declared at the job level override the same vars on individual tasks:

jobs:
  deploy-staging:
    description: "Deploy to staging"
    tasks:
      - db-migrate
      - build
      - deploy
    env:
      ENVIRONMENT:
        type: string
        default: staging

Every task in this job receives ENVIRONMENT=staging, overriding any task-level default.

Passing env from the CLI

meriadoc run job deploy-staging --env VERSION=1.2.3

CLI --env flags satisfy required env vars on any task in the job:

tasks:
  release:
    cmds: [echo "Releasing ${VERSION}"]
    env:
      VERSION:
        type: string
        required: true

jobs:
  publish:
    tasks: [release]
    env:
      VERSION:
        type: string
        required: true

meriadoc job publish --env VERSION=2.0.0   # works — satisfies task + job requirement

Failure handling

By default, a job stops at the first failed task. Use on_failure to control this:

jobs:
  resilient-ci:
    tasks:
      - lint
      - test
      - build
    on_failure:
      continue: true              # run remaining tasks even after a failure
      cmds:
        - echo "CI had failures — see above"

With continue: true, all tasks run regardless of earlier failures. The overall job still reports failure.

Dry run

meriadoc run job ci --dry-run

Shows the task sequence and each task’s resolved env and commands without executing anything.

Agent annotations

Jobs can have the same agent: block as tasks:

jobs:
  deploy-prod:
    tasks: [build, test, deploy]
    agent:
      risk_level: critical
      requires_approval: true
      confirmation: "PRODUCTION DEPLOYMENT. All tests passed. Proceed?"

See Agents / MCP for details.