Runs and results
Every run leaves a record
A run has a stable ID, timestamps, a final state, an exit code, logs, artifacts, events, and reproducibility data.
Run and job states
| State | Meaning |
|---|---|
queued | The request exists but execution has not started. |
running | The run or job is executing. |
succeeded | The run or job completed successfully. |
failed | A command, provider, setup, logging, or artifact operation failed. |
cancelled | An operator or signal stopped the run. |
skipped | A dependency prevented an ordinary downstream job from running. |
timed_out | A pipeline, job, or provider time limit expired. |
A run succeeds only when every selected job succeeds. A skipped job makes the run fail because its dependency failed. The original failure remains on the dependency record.
Process exit codes
| Code | Meaning |
|---|---|
0 | The command or run succeeded. |
1 | CLI or infrastructure failure. |
2 | Configuration or validation failure. |
3 | The run failed or timed out. |
4 | The run was cancelled. |
Inspect a run
contd runs --limit 20 contd status <run-id> contd logs <run-id> [job] contd artifacts <run-id> contd artifacts --all <run-id> contd inspect <run-id>
status reads saved run and job states. logs reads persisted streams without contacting Docker. inspect returns the complete run record, including events, dependency records, artifact references, and log references. Add --json for machine-readable output.
The follow stream reports run and job start, finish, and skip events. With --logs, it also reports live container streams and AI output. Interrupting follow detaches the client without cancelling the run.
Logs
Container stdout and stderr are captured separately. AI responses use the ai stream. Logs are redacted before saving. A log reference includes the stream, size, checksum, producing job, execution ID, and saved location.
Logs remain available after a container is removed. If a log cannot be saved, the job fails with an infrastructure failure rather than silently losing output.
Artifacts
Each artifact reference includes its ID, producing job, logical path, size, checksum, visibility, content type, and saved location.
contd artifacts --json <run-id> contd artifacts --all --json <run-id>
The default listing and normal downloads expose only exported artifacts. Internal artifacts are still transferred to dependent jobs and included in inspect.
contd artifacts download \ --output /tmp/report.tar \ <run-id> <artifact-id>
The download is a tar archive. The CLI rejects an internal artifact ID.
Cancellation
contd cancel --reason "operator stopped the run" <run-id>
Cancellation is durable and idempotent. The active engine polls the local cancellation record at a bounded interval, normally 100 milliseconds. It stops scheduling new jobs, cancels running work, waits for runtime cleanup, and saves the cancelled state. This is for one host, not a distributed control plane.
SIGINT and SIGTERM follow the same cleanup path.
Reproducibility
- A SHA-256 digest of the pipeline configuration.
- Git source URLs, requested references, and resolved commits when available.
- Container image tags and resolved image IDs when available.
- The effective environment after redaction.
- Host and contd version information.
- Timeout, network, filesystem, resource, and privileged-container policy values.
Unknown values are recorded as unavailable. An unlimited timeout is recorded as unlimited.