switchyard

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

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

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.

  1. Give the check paths: the files and folders it reads. A test build that changes nothing under them reuses the check's pass.
  2. 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 cache instead.
[[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.

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:

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

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.

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