The repo contract: .ithura/agent.yaml
Applies to: Hosted session and Your runner.
The repo contract is one file in your repository, .ithura/agent.yaml. It tells an agent how to set the repository up and which checks must pass before it reports its work. It is the same file for both kinds of agent.
The file
Put it at the root of the repository, at .ithura/agent.yaml.
version: 1
setup:
run: ["make", "deps"]
timeout_minutes: 20
verify:
max_fix_rounds: 2
checks:
- name: unit tests
when_changed: ["**/*.go"]
run: ["go", "test", "./..."]
timeout_minutes: 30
- name: lint
run: ["make", "lint"]
- version. Optional. Use 1.
- setup.run. The command that prepares the repository, written as a list of arguments.
setup.timeout_minutesdefaults to 20. - verify.checks. The checks. Each has a unique
nameand aruncommand written as a list of arguments.when_changedis an optional list of file patterns. When it is empty, the check runs for every change.timeout_minutesdefaults to 30. - verify.max_fix_rounds. How many more times the agent may fix failing checks and run them again. A hosted agent uses 2 when you leave it out. Ithura counts at most 5.
Commands run from the repository root. A field the file does not know is an error, so a typo is found instead of ignored.
Where the file is read from
The file is read from your base branch, not from the agent's branch. An agent cannot weaken its own checks by editing the file. If the agent's change touches .ithura/, the checks result flags it and the changed file is not used for that run.
No file means no checks
Without the file, setup does nothing and no checks run. The pull request says there are no checks configured, so a reviewer knows nothing was verified.
Check output must be git-ignored
Checks must not leave files in the repository that git would count as changes. If a check writes build output, test reports or caches inside the repository, add them to .gitignore.
The agent commits its work before it runs the checks. If files are uncommitted when the checks run, the result is marked as run on uncommitted work, and the server does not accept it. The agent has to clean up and run the checks again.
Hosted session
A hosted session runs ithura-agent setup first, then ithura-agent verify before it reports. The agent runs verify again until it returns, and it is told when to stop:
| Exit code | Meaning |
|---|---|
| 0 | The checks passed. |
| 1 | A check failed. Fix it and run again. |
| 3 | The checks are still running. Run the same command again. |
| 4 | Refused. The fix rounds are used up, or the checks keep dying. Report the failure. |
Ithura accepts the agent's report only when the checks belong to this run, passed, ran on committed work, and ran on the same commit that was pushed. The pull request lists each check and its result.
Your runner
The runner can use the same file through the ithura-agent setup and ithura-agent verify commands, which read it from the base branch. The runner's own check gate before it reports reads the verify block in its own config file, ithura-agent.yaml. The block has the same format. See Your runner.