Configuration

Describe the work

One YAML file defines the jobs, dependencies, stages, time limits, environments, sources, and outputs for a pipeline.

Configuration files

Without --config, contd checks these names in order:

.contd.yml
.contd.yaml
contd.yml
contd.yaml

An explicit relative path is resolved against the selected workspace. A daemon request must use a regular config file inside that workspace.

Top-level fields

env:
  - GLOBAL=value

stages:
  - build
  - test

timeout: 1h

jobs:
  build:
    ...

env supplies entries to every job. stages supplies ordering shortcuts. timeout bounds the whole pipeline and uses Go duration syntax such as 30s, 5m, or 1h30m. An omitted timeout is unlimited.

jobs must contain at least one named job. Job names appear in dependency references, status output, event records, and artifact metadata.

Container jobs

A job is a container job unless type: ai is set.

jobs:
  build:
    image: golang:1.25
    repo: git@github.com:example/project.git
    ref: main
    working_dir: /contd/project
    user: root
    env:
      - CGO_ENABLED=0
    before_script:
      - go version
    script:
      - go test ./...
      - go build -o /out/app ./cmd/app
    after_script:
      - echo "build finished"
    artifacts:
      - path: /out/app
        visibility: exported
    timeout: 10m

Field	Meaning
`image`	Required Docker image. contd pulls it when missing.
`repo`	Optional Git repository cloned into the container.
`ref`	Optional branch or tag. A shallow checkout is used.
`working_dir`	Directory used by scripts. With `repo` and no value, contd uses `/contd/<repository-name>`.
`user`	Container user.
`env`	Job-specific environment entries.
`before_script`	Commands run before `script`.
`script`	Main commands.
`after_script`	Commands run after `script` succeeds.
`artifacts`	Files or directories copied out after the container exits.
`timeout`	Job limit. The shorter of the job and pipeline limits ends the job.

Each script block becomes a separate /bin/sh script with set -e. The blocks run as before_script && script && after_script, so after_script does not run after an earlier failure. A nonzero command exit fails the job.

Container jobs run without a TTY. contd removes them after execution. The current runtime requests privileged containers, so use trusted images and scripts.

Environment values

The effective environment is assembled in this order:

Top-level env.
JOB_NAME and, for container jobs, JOB_IMAGE.
Job-level env.

Later entries take precedence when names repeat. Repository URLs support $NAME and ${NAME} expansion from top-level and job environments. An undefined variable fails validation.

Dependencies

Use a string when the downstream job should receive the upstream job's declared artifacts:

needs:
  - build

Use a mapping to disable transfer:

needs:
  - job: build
    artifacts: false

Artifact transfer defaults to true. A dependency controls scheduling and may provide logs, metadata, and artifacts to an AI job. A failed, cancelled, timed-out, or skipped dependency skips ordinary downstream jobs. AI jobs can still run after a failed dependency so they can inspect the failure context.

Stages

stages: [build, test, deploy]

Stages add dependencies from each job to every job in the immediately preceding stage. Explicit needs entries are preserved, and generated entries are added only when absent. A job without a stage is not included in stage-generated dependencies. Unknown stages, unknown jobs, and cycles fail validation before execution.

Artifacts

The short form marks an artifact as exported:

artifacts:
  - /out/report.txt

The object form sets visibility:

artifacts:
  - path: /out/intermediate.json
    visibility: internal
  - path: /out/report.html
    visibility: exported

exported artifacts are normal pipeline results. internal artifacts remain available for dependency transfer and diagnosis, but are hidden from the default listing and cannot be downloaded through the CLI. Missing artifact paths fail the producing job.

AI jobs

jobs:
  review:
    type: ai
    needs:
      - verify
    sources:
      - name: current
        current: true
    prompt: Review /artifacts/verify/review/final-report.md and write /output/review.md
    model: GPT-5.6 Luna
    reasoning: High
    context_window: 328k
    data_policy: local-only
    artifacts:
      - path: /output/review.md
        visibility: exported
    limits:
      max_turns: 8
      max_tokens: 16000
      max_duration: 5m
      max_network_requests: 8

AI jobs cannot set container fields such as image, repo, script, or env. They are read-only except for declared output paths. See AI jobs for the workspace contract.

The current Copilot adapter accepts GPT-5.6 Luna, reasoning levels low, medium, high, xhigh, and max, and the 328k context window.

Selection options

--job NAME includes NAME and all of its prerequisites.
--from NAME includes NAME, its downstream dependents, and the prerequisites needed by those dependents.

The selection is resolved against the dependency graph before the run starts.