for agents: this page is markdown at https://switchyard.so/docs/faster-checks.md; every page is listed in llms.txt.
Make checks and clones start faster
Shorten the time before a check's command starts, and the time an agent waits for its clone.
You will have: checks that check out only what they read, passes that are reused, and clones that download only what the machine lacks. Works with: .yard/rules.toml, yard, plain Git. Switchyard turns on starts from a saved disk for a project when you ask.
Each section is one change. Make the changes that fit your repository, in any order. Write rules and checks explains every key of the rules file used here.
Before you start
- A project with at least one check that runs on Switchyard's machines. A check that waits for GitHub's checks starts on GitHub, and nothing here changes it.
- A project admin, to save rules and change settings: an owner or admin signed in, or the project admin key.
Measure a check's start
Read how long each part of a check's start took.
yard status --json
Each check that ran on a Switchyard machine carries stages, in milliseconds, under mergeQueue.testBuilds[].checks[]; yard check log --json prints it too: stopMs is the stop of the machine before it, startMs the machine's start, networkMs the network filter, treeMs the checkout, cacheMs the build cache, and launchMs the command's launch. A large treeMs means that the checkout is the part to shorten.
A check is billed for the time its command runs. The time before the command starts is not billed.
Check out only what a check reads
Without checkout, a check's machine gets the whole tree. Name the files or folders that the check reads, and the machine gets only those.
[[check]]
name = "api tests"
command = "cd services/api && npm ci && npm test"
checkout = ["services/api", "packages/shared"]
skeleton = true
checkouttakes one to sixteen files or folders, without wildcards. A path that the commit does not have fails the check by name.skeleton = trueadds the top-level files and every build manifest outside the list, such aspackage.jsonand lockfiles. A monorepo's build tools then see every package while the sources stay out.
A check with checkout tests only the files it reads. A change to any other file needs another check that reads it, or an [[unchecked]] table. Say which paths need no check explains the hold.
Let a check reuse its pass
A check that reuses a pass starts no machine and costs nothing.
- Give the check
paths: the files and folders it reads. A test build that changes nothing under them reuses the check's pass. - Pin what the command downloads, with a lockfile. A pass on exactly the same tree is then reused for good. Reuse a pass says when to set
cacheinstead.
[[check]]
name = "web build"
command = "npm ci && npm run build"
paths = ["apps/web", "package-lock.json"]
Keep Git's file contents out of the checkout
By default, the .git folder of a check's checkout holds the commit and its trees, and no file contents. git status, git rev-parse, git ls-files and git log of the commit work.
Set git = "full" only on a check whose command reads file contents from Git, such as git diff after the command changed a file. The machine then also writes every checked-out file into .git, which takes longer.
[[check]]
name = "generated files are current"
command = "npm ci && npm run generate && git diff --exit-code"
git = "full"
Keep the checks that run ahead
Two project settings run a task's checks before the merge queue needs them. Both are on by default. Keep them on unless you have a reason.
checks-before-submit: a task's checks run on its latest pushed commit once 30 seconds pass with no push. A pass is then ready when the agent submits. Such a run is billed only when the submit reuses its pass. A project starts at most 30 of these check runs in an hour.checks-while-reviewing: a task that waits for a person's review runs its checks while it waits, so an approval can merge at once.
yard settings prints the project's settings. yard settings set checks-before-submit on turns the first on again.
Keep the build cache on
Checks keep their package downloads between runs when the project's build-cache setting is on, which is the default. The cache is keyed by the lockfiles, so commit a lockfile at the repository root or at each checkout root. Read a failed check has the cache's sizes.
Start checks from a saved disk
A check can start from a saved disk: a copy of a machine that already holds main's checkout. The check's machine then fetches only the files that changed since the disk was saved, where a fresh setup unpacks the whole tree.
Starts from a saved disk are off by default. Switchyard turns them on for one project at a time. To ask, write to support@switchyard.so with the project's id. You change nothing in the rules file.
Once they are on, a check starts from a saved disk when all of these are true:
- the check has no
checkoutlist, so it takes the whole tree; - the check does not set
git = "full"; - the check starts no
services.
Every other check takes a fresh setup, as before. So does any check whose saved disk does not match its commit exactly. Guarantees states what Switchyard promises about a saved disk, and limits says how long a saved disk can stay after its project is deleted.
Make a clone faster
A task's clone is plain Git, so three things shorten it.
Start the task from inside a clone of the repository. Run yard branch new in any clone of the repository on that machine. The new clone borrows the objects that the first clone already has, and downloads only what the machine lacks.
yard branch new 'Add sales tax to cart totals' --dir sales-tax
Use the clone you are in. --here checks the task out in the current repository and clones nothing. It is refused in a clone that already holds a task.
yard branch new 'Add sales tax to cart totals' --here
With plain Git, clone less. A task's remote serves shallow, blob-less and sparse clones.
git -c http.extraHeader="Authorization: Bearer <git key>" clone --depth 1 --filter=blob:none --sparse --branch <git branch> <git remote> work
--depth 1fetches the task's last commit without its history.--filter=blob:nonefetches a file's contents only when Git needs them.--sparsechecks out only the top-level files.git sparse-checkout set <folder>then adds the folders the agent works in.
A push from such a clone lands like any other push. Switchyard's own load runs clone tasks this way.
Wake the Git engine ahead of work
A project's Git engine stops when it is idle. The first clone, push or check after that waits while the engine loads the repository from storage.
Wake the engine before a batch of agents starts. A project admin does this.
yard engine wake --wait
--wait stays until the engine is awake. MCP: yard_wake_engine.
Two project settings wake the engine without a command. Both are on by default for a repository above 1 GB.
yard settings set wake-on-open on: the engine wakes when someone opens the project.yard settings set warm-hour on: the engine stays awake for an hour after the last push, task, check or open.
An engine that is awake is billed as engine time. Pay and set a spending limit says how engine time is billed.
Verify
Submit a task, then run yard status --json again. Compare treeMs of the same check with the first reading.
Next
- Write rules and checks: every key of a
[[check]]table. - Limits: machine sizes, and how many check machines run at once.
- Guarantees: what is promised about the commit a check runs on.