AI jobs

Give an AI review a safe workspace

An AI job receives approved source snapshots and dependency context through logical paths. It can inspect files, search text, fetch requested documentation, and write only declared output files.

Documentation home · Interactive AI guide

Configuration

jobs:
  review:
    type: ai
    needs:
      - verify
    sources:
      - name: current
        current: true
      - name: upstream
        repo: https://github.com/example/upstream.git
        ref: v2.4.1
    prompt: |
      Review /artifacts/verify/check/report.md.
      Compare it with /sources/upstream/ 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_context_bytes: 262144
      max_artifact_bytes: 131072
      max_artifacts: 8
      max_turns: 8
      max_tokens: 16000
      max_duration: 5m
      max_network_requests: 8

Field	Meaning
`type`	Must be `ai`.
`prompt`	Required provider instructions.
`model`	The current adapter accepts `GPT-5.6 Luna`.
`reasoning`	`low`, `medium`, `high`, `xhigh`, or `max`.
`context_window`	The current adapter accepts `328k`.
`data_policy`	`local-only` or `redacted-remote`.
`sources`	Named current or Git source snapshots.
`limits`	Context, artifact, turn, token, duration, budget, and network caps.
`artifacts`	Declared logical output paths.

AI jobs cannot set image, working_dir, user, repo, ref, env, or script fields. Their filesystem access is read-only except for declared outputs.

Sources

Each source has a unique safe name. The name becomes part of its logical path.

sources:
  - name: current
    current: true

Use a shallow checkout at a branch or tag:

sources:
  - name: release
    repo: git@github.com:example/project.git
    ref: v3.2.0

Remote sources require both repo and ref. The reserved name current is valid only with current: true. A source checkout failure fails the AI job before the provider session starts.

The current source excludes Git internals, contd state, credentials, common credential files, SSH keys, dependency directories, virtual environments, .env files other than .env.example, and files ending in .pem or .key. A non-Git current directory still works, but has no Git revision metadata.

contd reuses local Git authentication while preparing a source. It does not put Git credentials or credential-bearing URLs in the workspace or prompt.

Logical workspace paths

/sources/<name>/
/artifacts/<stage>/<job>/...
/logs/<stage>/<job>/stdout.log
/logs/<stage>/<job>/stderr.log
/metadata/<stage>/<job>.json
/metadata/sources/<name>.json
/metadata/diffs/<source-name>.patch
/<declared-output>

These are workspace paths, not host paths. Sources, dependency inputs, logs, and metadata are read-only. Use the same absolute path in the prompt, write_output, and artifact declaration.

The roots /sources, /artifacts, /logs, and /metadata are protected. Dependency paths include stage and job names. The dependency closure includes direct and transitive dependencies.

Workspace tools

Tool	Use
`read_file`	Read a UTF-8 text file. Individual reads are capped at 256 KiB.
`list_paths`	List immediate children of a logical directory.
`search_text`	Find text and return matching paths and line numbers.
`write_output`	Write one declared output file.
`fetch_url`	Fetch explicitly requested HTTP or HTTPS documentation.

Shell commands, arbitrary filesystem writes, Git commands, deployment tools, and agent spawning are not available. fetch_url is limited to HTTP and HTTPS, the configured request count, and 256 KiB per response.

Outputs

artifacts:
  - path: /output/review.md
    visibility: exported

The prompt and write_output call must use the same logical path. Output paths cannot replace source files, dependency artifacts, logs, or metadata. Declared output content is capped by max_artifact_bytes when set.

If no output is declared, contd still saves the provider's structured AI report as an internal artifact. A successful AI job also saves the input manifest as an internal artifact.

Provider and limits

The current provider is the GitHub Copilot SDK. It uses the local logged-in GitHub CLI or Copilot account and keeps the provider session bound to the temporary workspace.

Limit	Default
`max_context_bytes`	131072
`max_artifact_bytes`	16384
`max_artifacts`	4
`max_turns`	1
`max_tokens`	1000
`max_network_requests`	8

Set max_duration to bound the provider call. Set max_budget when the provider reports a compatible usage budget. Provider usage is recorded when available, otherwise contd records unavailable.

Cleanup and provenance

contd deletes the temporary workspace after execution. It retains an input manifest with source names and revisions, dependency paths, checksums, sizes, unavailable inputs, output paths, and cleanup status. The manifest does not contain source contents or credentials.

The AI analysis artifact records provider settings, data policy, limits, prompt hash, input manifest reference, source metadata, response summary, evidence, next checks, confidence, and usage when available.

AI jobs after failures

Ordinary jobs are skipped when a dependency fails. AI jobs can run after a failed or timed-out dependency and receive that dependency's state, failure, logs, artifacts, metadata, and reproducibility information.