Appendix: Patchset CI Configuration
Define the canonical RC.6 Patchset CI suite catalog, supported runners, checks, artifacts, and bounded local locator.
Audience: Repository owners, CI maintainers, and operators
Patchset CI configuration#
ci/patch_ci.json is the canonical RC.6 suite catalog used when a Repository is registered with an AIT server and when remote readiness requests Patchset CI. The catalog must contain at least one blocking Patchset gate.
Minimal command-bundle catalog#
{
"schema_version": 1,
"suites": [
{
"schema_version": 1,
"suite_id": "patchset_gate",
"display_name": "Patchset Gate",
"plane": "patchset",
"mode": "gate",
"default_blocking": true,
"purpose": "Validate this repository before remote land.",
"runner": {
"kind": "command_bundle",
"commands": ["./ait.sh test"]
},
"artifacts": {
"log_path": ".ait/generated/ci/patchset_gate.log",
"summary_json": ".ait/generated/ci/patchset_gate.json"
}
}
]
}ait remote add creates a starter catalog when the file is missing and then stops so the placeholder command can be replaced. It never overwrites an existing catalog. The placeholder replace-with-your-ci-command is rejected.
Catalog and suite fields#
| Field | Contract |
|---|---|
schema_version | Top-level integer 1; required. The starter also records 1 on each suite. |
suites | Array of suite objects. At least one object must be a named, runnable blocking Patchset gate. |
suites[].suite_id | Nonempty unique operational name. Required for every selected blocking gate. |
suites[].display_name | Optional human-readable string. |
suites[].plane | Use patchset for Patchset CI selection. |
suites[].mode | Use gate for readiness selection. |
suites[].default_blocking | Boolean. true makes the selected suite part of readiness evidence; false is informational. |
suites[].purpose | Optional explanatory string. |
suites[].runner | Required object with a nonempty supported kind. |
suites[].artifacts.log_path | Optional relative log-artifact path. |
suites[].artifacts.summary_json | Optional relative JSON-summary path. |
Only suites whose plane and mode resolve to patchset and gate are planned. A catalog used for first registration needs at least one such suite with default_blocking: true. Do not rely on unknown keys as extension points.
command_bundle runner#
This runner executes shell command strings in order and stops after the first failure. Prewarm and main commands share the admitted environment.
| Runner field | Type and behavior |
|---|---|
kind | Exact string command_bundle. |
commands | Nonempty array of nonempty shell-command strings. |
prewarm_commands | Optional array executed before commands. |
env | Optional object of string environment values added to the clean CI process environment. |
runner_parallelism | Optional positive integer used for admitted command parallelism. |
cpu_tokens | Alias for runner_parallelism. |
workers | Lower-precedence alias for runner_parallelism. |
timeout_seconds | Optional positive bounded timeout applied to each process. |
The scheduler can supply a stricter admitted parallelism value. Configuration does not grant CPU capacity by itself. Full logs and the bounded JSON summary are separate artifacts.
test_discovery_sharded runner#
This runner discovers test cases, builds the selected test executables, and runs bounded shards. It supports Cargo and a generic command adapter.
Common fields#
| Runner field | Type and behavior |
|---|---|
kind | Exact string test_discovery_sharded. |
adapter | cargo by default; command selects the generic adapter. |
env | Optional string-to-string environment object. |
runner_parallelism, cpu_tokens, workers | Positive-integer parallelism names, in that precedence order. |
timeout_seconds | Optional positive bounded process timeout. |
exclude_test_cases | Optional array of exact discovered test-case names to omit. |
checks | Optional pre-test check array described below. |
Cargo-adapter fields#
| Runner field | Type and behavior |
|---|---|
cargo_binary | Cargo executable name or path; default cargo. |
manifest_path | Normalized relative path; default Cargo.toml. |
workspace | Boolean; default true. |
build_args | Optional argv strings replacing the default Cargo build arguments. |
doc_tests | Boolean; default false. Not accepted with the command adapter. |
doc_test_args | Optional argv strings for documentation tests. |
Command-adapter fields#
| Runner field | Type and behavior |
|---|---|
discovery_program | Required nonempty executable name or path. |
discovery_args | Optional discovery argv array. |
discovery_output_format | json_array by default, or lines. |
run_program | Required nonempty executable name or path. |
run_args | Optional run argv array. |
append_test_items | Boolean; when true, discovered item names are appended to the run argv. Default false. |
working_directory | Normalized relative directory inside the workspace; default is the workspace root. It must exist. |
Pre-test checks#
checks entries accept check_id, kind, file_name_suffix, exclude_dirs, and args. Missing check_id becomes check-N.
kind: "forbid_files"fails if a file ends withfile_name_suffixoutside the named directory components. The suffix defaults to.py.kind: "cargo_fmt"runs Cargo formatting verification.argscan replace its default argv.
Other check kinds are rejected when the suite runs.
Optional build cache#
runner.build_cache accepts policy and executable_manifest_path. The only enabling policy is reuse_when_rust_inputs_unchanged; absence or another value keeps reuse disabled. Changed-path evidence is supplied by the execution request and should not be authored as static catalog data.
Optional local locator: ci/config.contract.json#
When ci/patch_ci.json is absent, local workflow command discovery can read:
{
"schema_version": 1,
"ci": {
"suite_manifest_path": "config/patchset-suites.json"
}
}RC.6 reads only the nonempty ci.suite_manifest_path value and uses it only if the referenced file exists. A present ci/patch_ci.json always wins. Remote Repository registration still validates and publishes the canonical ci/patch_ci.json; the locator does not redirect that registration contract.
Operational checks#
ait remote add origin https://server.example.invalid --default
ait workflow ready <change-id> --apply
ait task audit <task-id>ait workflow ready is the decision surface for the current Patchset. Passing a locally invoked test command does not substitute for the server evidence required by a remote Task.