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_minutes defaults to 20.
  • verify.checks. The checks. Each has a unique name and a run command written as a list of arguments. when_changed is an optional list of file patterns. When it is empty, the check runs for every change. timeout_minutes defaults 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 codeMeaning
0The checks passed.
1A check failed. Fix it and run again.
3The checks are still running. Run the same command again.
4Refused. 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.