switchyard

for agents: this page is markdown at https://switchyard.so/docs/rules.md; every page is listed in llms.txt.

Write rules and checks

Write a rules file so that the merge queue runs your checks and knows which changes merge without a person.

You will have: a .yard/rules.toml that the merge queue reads on every test build, with your checks, review rules and owned paths. Works with: yard, the board's settings page, MCP (yard_rules_keep), REST (PUT /v1/projects/{project}/rules), or a commit to main.

The rules file holds the checks the merge queue runs, the review rules that decide which changes wait for a person, the paths a team owns, and what the checks may reach. How the merge queue batches and tests is on the architecture page.

Prerequisites

Step 1 — Choose where the file lives

The file lives in one of two places. A file on main always wins: Switchyard reads the rules it keeps only while main has no .yard/rules.toml.

  1. In Switchyard. Write the file, then run yard rules keep rules.toml. A project admin does this. Set-up keeps the file here when it writes no workflow change, so nothing merges into the repository to begin. yard rules show prints the rules Switchyard keeps. Add --try to yard rules keep to run the new or changed checks once on main first: they stay off until they pass there.
  2. In the repository. Commit the file as .yard/rules.toml on main. The merge queue reads the version on main. A change to any file under .yard/ merges like any other change, but always waits for a person.

Warning: on hosted Switchyard, a change to the kept rules that loosens them needs a person signed in in a browser within the last 15 minutes. A key or a yard sign-in is refused. A change loosens the rules when it changes or drops a rule, adds a rule that merges without review, drops a check, eases an owners table, or adds an [[unchecked]] table. Make such a change on the settings page.

The file takes seven top-level keys: [[check]], [[rule]], [[owners]] and [[unchecked]] tables, network, a [merge_queue] table and a [github] table. The parser refuses any other key. Kept rules are at most 64 KiB.

You know where the file lives. Next, you add a check.

Step 2 — Add a check

A check is a command the merge queue runs on a fresh machine, with the test build checked out and no secrets. Write one [[check]] table for each command.

[[check]]
name = "test"
command = "npm ci && npm test"
size = "small"
timeout = "15m"

[[check]]
name = "build"
command = "npm run build"
paths = ["packages/app", "package-lock.json"]

[[check]]
name = "mlir configures"
command = "cmake -S llvm -B build -DLLVM_ENABLE_PROJECTS=mlir -DLLVM_TARGETS_TO_BUILD=host"
checkout = ["cmake", "libc", "llvm", "mlir", "third-party"]
KeyMeaning
nameThe check's name: at most 64 characters, one line of plain text (see Labels), unique in the file. The board and the merge record show it.
commandThe shell command, at most 4,000 characters, run in the checked-out tree.
size"small" or "large": the machine it runs on. Without it, the check runs small when its checkout fits a small machine. The pricing page has the rates.
timeoutHow long it may run, such as "90s", "15m" or "1h". At most one hour. 10 minutes when left out. A check that reaches it is timed_out, and the merge queue treats it as failed.
pathsOne to sixteen files or folders, without wildcards, that the check reads. Switchyard keeps a pass under the contents of these paths (and checkout), so a test build that changes nothing under them reuses the pass.
checkoutOne to sixteen files or folders, without wildcards: the only paths the check's machine gets. Without it, the machine gets the whole tree. A path the commit does not have fails the check by name.
skeletontrue, with checkout only. The machine also gets the top-level files and every build manifest outside the checkout list (package.json and lockfiles, Cargo.toml, go.mod, pyproject.toml and the like), so a monorepo's build tools see every package while the sources stay out.
cacheHow long a pass is reused for exactly the same tree. true (the default) reuses it for good, false never, and a duration up to "30d" runs the check again once the pass is that old. A github check defaults to one day.
servicesThe databases the check's machine starts before the command. See Start a database for a check.
reportsOne to sixteen paths or globs, at most 200 characters each, where the command writes JUnit XML reports. Without it, Switchyard reads junit*.xml, test-results/**/*.xml, target/surefire-reports/*.xml and build/test-results/**/*.xml.
git"full" keeps every checked-out file's contents in the checkout's .git, for a command that reads them from Git, such as git diff of a changed file, or that makes a tree or a commit, such as git write-tree, git commit or git stash. Without it, .git holds the commit and its trees and no file contents, and those commands fail.
githubInstead of command: the name of a GitHub check to wait for, or "*" for every check. It takes no size, paths, checkout, skeleton, services, reports or git.
github_appWith github only: the GitHub app whose check runs count, by its slug, such as "github-actions", or its id as a number. Without it, Switchyard learns the app from main's checks. See Which GitHub checks count.

A check has command or github, never both.

The project has its checks. Next, you say which files need none.

Step 3 — Say which paths need no check

Every file a test build changes must be read by a check that passed on it, or the rules must say that it needs none. If not, the merge queue holds the change and names the files no check reads. A rules file with no checks holds nothing. Write an [[unchecked]] table for paths that need no check:

[[unchecked]]
paths = ["deploy/**", "infra/**"]
exclude = ["deploy/scripts/**"]
reason = "deployed by hand from a release tag, never run by a check"

paths and exclude are globs. reason is one sentence of at most 200 characters. yard rules unchecked <path>... --reason '<why>' adds the table to the rules kept in Switchyard. When the rules live on main, the command is refused and names the table to add in a task.

Documentation needs no check by default: Markdown, reStructuredText and AsciiDoc files, images under docs/, and licence, notice, copying and author files. Files under .yard/, .github/workflows and .github/actions are never excused as documentation. yard settings set docs-excused off makes documentation need a check like any other file. .yard/rules.toml itself needs no check: a change to it always waits for a person.

A project made before this guard shipped watches for seven days first, and shows on the board what it would have held. Then it holds. yard rules enforce starts holding at once.

Every changed file is covered. Next, you write the review rules.

Step 4 — Write a review rule

A rule matches a change and says what happens to it. Switchyard reads the rules in order for each changed path, and the first match decides for that path. The strictest result across the paths decides for the change. A path no rule covers waits for a person.

[[rule]]
name = "docs merge on their own"
match = { path = "^docs/" }
policy = "auto-merge"

[[rule]]
name = "secrets never merge"
match = { added = "AKIA[0-9A-Z]{16}" }
policy = "block"

[[rule]]
name = "payments wait for a person"
match = { path = "^src/payments/" }
policy = "human-review"
reviewers = ["ada", "grace"]
KeyMeaning
nameWhat the rule is for. The board, the inbox and the merge record use it.
match.pathA regular expression a changed path must match.
match.addedA regular expression an added line must match. With both, a path matches when it matches both. Without match, the rule covers every path. The expressions are RE2: lookahead, lookbehind and backreferences are refused.
policy"auto-merge": merges once its checks pass. "human-review": waits for a person. "block": never merges.
reviewersNames of the people who should look at it, shown with the rule on the settings page.
judgeA yes-or-no question a judgment service answers about the change, such as "does this change the public API?". The rule applies when the answer is yes. When the answer is no, the next rule is tried. When no answer comes, the change waits for a person.
thresholdWith judge only: how sure the judge must be, from 0 to 1. 0.5 when left out.
protectedtrue on a "human-review" rule: a person other than the task's people (who started it, its assignee, who pushed and who wrote its commits) must approve. When nobody else could approve, the rule does not hold the change. yard settings set self-approval on lets people approve their own.

yard rules protect lists the protected areas the repository has and the rules miss, such as migrations and agent instructions. yard rules protect --add adds them. yard settings set reviews off adds a last rule that lets every change no rule covers merge once its checks pass. Review a change has this setting.

Warning: on hosted Switchyard, reviews off, self-approval on and docs-excused on loosen a review gate. A person signed in in a browser within the last 15 minutes sets them on the settings page. A key or a yard sign-in is refused.

The rules decide what waits. Next, you check the file.

Step 5 — Check the file

  1. Save the file with yard rules keep rules.toml, or commit it to main. The parser refuses an unknown key, a policy outside the three, a regular expression that does not compile, a duration it cannot read, or two checks with one name. A TOML syntax error names the line. Any other error names the table and its number, such as rule 2:.
  2. Submit a task. The merge queue's first test build shows the checks by name.
  3. Run yard verify <commit> on the first merge. The merge record names the checks that passed and, for each change, who approved it or that the rules let it merge.

Labels

A label is one line of plain text. A check's name and github, a rule's name, reviewers and judge, an unchecked reason, an owners team and the [github] queue_label may not hold a control character (such as a tab or a new line), a line or paragraph separator, or a character that changes the direction of text. The parser names the table, the field and the character, as in check 1: name holds U+0009 (tab). Remove the character and save again. Emoji are allowed.

Verify

Open the project's settings page. It shows the rules source (repository or switchyard), each check with its services, and each rule. yard rules show prints the kept rules.

Reuse a pass

A check that passed on exactly the same tree, with the same command, network, services, git and checkout, does not run again: the merge queue uses that pass. A project keeps its last 20,000 passes. A check that reads something outside the tree can pass today and fail tomorrow on the same code, so give it a cache duration:

[[check]]
name = "unpinned"
command = "pip install pytest requests && python -m pytest"
cache = "1d"

[[check]]
name = "links"
command = "npm run check-links"
cache = false

A check with a lockfile (npm ci, cargo test --locked, every version pinned) needs neither.

Start a database for a check

List the databases a check's tests need in services. The check's machine starts them before the command runs. Docker is not needed.

[[check]]
name = "test"
command = "python manage.py test"
services = [
  { name = "postgres", version = "17", env = { POSTGRES_PASSWORD = "postgres", POSTGRES_DB = "app_test" } },
  { name = "redis", host = "cache" },
]
ServiceVersionPortenv it takes
postgres"17"5432POSTGRES_USER, POSTGRES_PASSWORD, POSTGRES_DB, POSTGRES_HOST_AUTH_METHOD, POSTGRES_INITDB_ARGS
redis"8.0" (or "8")6379REDIS_PASSWORD
mysql"11.8" (or "11"): MariaDB 11.8, which speaks MySQL's protocol3306MYSQL_ROOT_PASSWORD, MYSQL_ALLOW_EMPTY_PASSWORD, MYSQL_DATABASE, MYSQL_USER, MYSQL_PASSWORD
mariadb"11.8" (or "11")3306MARIADB_ROOT_PASSWORD, MARIADB_ALLOW_EMPTY_ROOT_PASSWORD, MARIADB_DATABASE, MARIADB_USER, MARIADB_PASSWORD, and the mysql names
KeyMeaning
nameOne of the services above, each at most once in a check. mysql and mariadb not together.
versionThe version the machine runs, as in the table. Leave it out to take it. Another version is refused.
envThe settings the service reads, by the names in the table.
portAnother port, from 1024 to 65535, when the tests expect one. Two services on one port are refused.
hostOne more hostname for the service, such as "db", at most 63 characters and not localhost.

The services listen on 127.0.0.1. The machine knows each one by its service name and its host. Each service must answer its health check within 60 seconds. When one does not, the command does not run, and the check fails with the service's name and the last lines of its log.

Read a failed check

  1. Run yard check log <name>. It prints the check's full log, kept for 30 days. A log over 50 MB keeps its first and last 25 MB. --build <id> picks a test build, and --trial picks the trial on main. With --json and no name, each check also carries its tests and the stage that failed.
  2. Run yard check shell <name> -c "<command>" to look inside the machine of a task's failed check. The command runs through bash -c in the check's folder, for up to 2 minutes and 1 MB of output, and yard exits with the command's status. The machine stays for 10 minutes after the check fails or after the last command, up to 30 minutes. yard check shell <name> --done ends it. Its time is billed as check time, at least one minute for each kept machine.
  3. Run yard check tried to see how the kept checks did on their trial on main, and which are off. A check that fails on main itself is turned off at set-up, so that it does not hold every task. yard check off <name> and yard check on <name> turn kept checks off and on. yard check try runs the checks that are off once more on main. Trials are free, up to 100 runs a UTC day, and a large check counts as four.

Failed machines are kept by default on the Scale and Enterprise plans. A project admin sets yard settings set keep-failed-machines on, off or plan (as the plan does).

Checks keep their package downloads between runs by default, at most 2 GiB for each cache and three caches. A cache is keyed by the lockfiles at the repository root and at each checkout root. A cache saved by a task is used by other tasks only after that task's tree merged on main. yard settings set build-cache off turns the cache off.

Warning: on hosted Switchyard, yard check off loosens a review gate, so a person signed in in a browser within the last 15 minutes turns a check off on the settings page.

Read each test on its own

When a check's output names its tests, Switchyard keeps each test on the check's record: its name, whether it passed, failed or was skipped, and the first lines of a failure. yard status --json and yard check log --json carry them.

Switchyard reads the JUnit XML reports the command wrote (under reports, or the default places). Without reports, it reads the output of pytest, cargo test, go test and jest. A report committed to the repository is never read.

[[check]]
name = "java"
command = "./gradlew test"
reports = ["build/test-results"]

A check that fails or times out runs once more before any task is blamed. The second run runs only the failed tests, at most 100 of them, when the output named every failed test and the command is pytest, go test, cargo test --no-fail-fast or jest (with their usual launchers, such as python -m pytest, uv run pytest or npx jest). If not, the whole check runs again. If the second run passes, the check counts as passed on that tree and the test build continues.

Use tests on GitHub Actions

Both ways need the project to follow a GitHub repository.

  1. Wait for GitHub's own checks. Write a [[check]] with github = "<check name>", or github = "*" for every check. Switchyard pushes each test build to a switchyard/test/ branch of the repository, your workflows run on it, and the merge queue reads their result. Add switchyard/test/** to the workflow's push branches. You pay your CI provider and not Switchyard. The pass of such a check is reused for one day unless the check sets cache.
  2. Run the jobs on Switchyard's machines. Label a job runs-on: switchyard (a small machine) or runs-on: switchyard-large. Switchyard registers a one-job runner with GitHub, and the job runs there with the secrets GitHub gives that job. Switchyard stores none of them. The job's minutes are check minutes. A job GitHub does not give to the runner within 5 minutes is given up. A job runs at most 60 minutes. A machine that fails to start is started once more.

Which GitHub checks count

A check counts the runs of one GitHub app only:

Switchyard trusts an app for a name because the app posted that name on main. Only an app installed on the repository, or a workflow on main, can do that. So anyone who can install an app on the repository or change main's workflows can post a check that counts. GitHub's own required checks with any source trust the same people.

A run of the same name from another app is not counted, whatever its result. When only another app posts the name, the task waits, and its status names that app. When main has the name from two apps, the task waits until github_app names one. To move a check to another CI, set github_app to the new app.

With github = "*", every app's checks count except Switchyard's own. The check passes only when all of these are true:

A workflow that never starts holds the task at the check's timeout. The task is not sent back, and the check never passes. When a check must not wait for every workflow, name it instead of "*".

An app that posts checks on main but not on test builds, such as a deploy, preview or code analysis app, is waited for 3 minutes. If it has not started by then, the task waits, and its status names the app. Choose one fix:

The merge queue looks at such a task again after 30 minutes, or sooner when main or the rules change, and the task's status says when. It reads the checks on the build it already pushed first, so an app that was only slow lands the task without running your CI again.

A job that GitHub skipped, by its if: condition or a path filter, does not fail a check. When a skip counts:

A task that waits because a check came from the wrong app, or because GitHub skipped every check for "*", does not run your CI again every five minutes for the same answer.

When a GitHub check holds a task

A hold from a GitHub check comes from the project's setup or from GitHub, not from the task's code. Nothing is sent back, and the agent has nothing to fix. The task's status carries one sentence. Find its words in the table.

The sentence containsIt meansTo clear it
not counted: Switchyard countsOnly an app that does not count posted the check's name on the test build. Every task with this check meets the same hold.Set github_app on the check to the app that is your CI. The merge queue tries again when main or the rules change, or after 24 hours.
cannot tell which is your CI and counts none of themTwo apps post the check's name on main.Set github_app to one of them.
GitHub ran no checkNo workflow ran on the test build within 3 minutes, or the job has another name on GitHub.Add switchyard/test/** to the workflow's push branches, check the name GitHub shows for the job, or turn on the repository's workflows. The merge queue tries again when main or the rules change, or in five minutes.
GitHub skipped every check on the test buildWith github = "*", GitHub skipped every check, so nothing tested the change.Let a job run on pushes to switchyard/test/**, or name the checks to wait for. A task that was tested on its own is set aside and tried again when it or main changes, or after 24 hours.
but named no workflow runGitHub skipped the named check and did not say which workflow run it belongs to. Switchyard cannot tell a skip by your workflow from a job whose needed job failed, so the check neither passes nor fails.Nothing in the rules. A task that was tested on its own is tried again when it or main changes, or after 24 hours.
posts checks on main but ran nothing on the test buildWith github = "*", an app that posts checks on main did not start on the test build within 3 minutes.Count only your CI's app with github_app, name the checks to wait for, or let that app run on switchyard/test/** branches in its own settings. The merge queue reads the build's checks again after 30 minutes, or sooner when main or the rules change.
and no run of it started withinGitHub made a workflow run for the test build, and it did not start within the check's timeout. A concurrency group or a required approval holds it.Free or approve the workflow on GitHub, or name the checks to wait for instead of "*". The merge queue tries again when main or the rules change, or in five minutes.
could not push the test buildGitHub refused the push of the test build to its switchyard/test/ branch. GitHub's reason comes after the colon.When a rule of the repository refuses it, let the Switchyard App push switchyard/test/** branches. When the repository is archived, unarchive it. When GitHub says the App lacks a permission, such as workflows for a change under .github/workflows/, accept that permission for the App. The merge queue tries again when main or the rules change, or in five minutes.
does not follow a GitHub repositoryThe check has github, and the project follows no repository.Follow a repository in the project's settings, or give the check a command.
waits to run on GitHub ActionsGitHub does not answer.Nothing. The check runs when GitHub answers. Status and outages has the detail.

A check that is still running on GitHub when its timeout ends is different: it is timed_out, and the merge queue treats it as failed.

Set what the checks may reach

network = "registries"

The value is "open", "registries" or "off". registries lets a check read from package registries and GitHub's downloads, and nothing else: this is enough for npm ci and cargo build. off is for tests that need nothing outside the tree.

The project also has its own setting, yard settings set check-network <value>. A new project starts on registries. A check runs under the stricter of the setting and the file's network.

Own paths as a team

A team's approval is needed before a change to the paths it owns merges, whatever the rules decide. A block rule still stops the change.

[[owners]]
team = "infra"
paths = ["deploy/**", "infra/**"]
exclude = ["infra/docs/**"]
approvals = 1
KeyMeaning
teamThe team's name as the organization knows it: one word, at most 100 characters.
pathsPaths or globs the team owns. "**" is every path.
excludePaths or globs inside them that the team does not own.
approvalsHow many of the team's members must approve, from 1 to 20. 1 when left out.

Share the merge queue fairly

When many agents submit at the same time, weights and aging decide whose task is tested first.

[merge_queue]
weights = { "fleet:F2" = 0.5, "person:ada" = 2 }
aging = "2h"
priority = ["person:oncall", "fleet:F7"]

Each turn costs a key one unit divided by its weight, so a key of weight 2 gets twice the turns and a key of weight 0.25 a quarter of them. A key not named weighs 1. Keys are fleet:<id>, person:<login> or agent:<id>, with weights from 0.01 to 100, at most 1,000 keys.

priority lists the keys whose tasks merge in the priority lane: after hotfixes and before every other task. Up to 1,000 keys, in the same form as weights. The rules never make a hotfix: only a project admin does that, one task at a time, with yard hotfix.

A task that has waited longer than aging goes in with the priority lane. aging is 5 minutes when left out, at most 7 days. Merge lanes explains the three lanes, and Move a task ahead in the merge queue has the steps for each.

depth is the most batches the merge queue tests at the same time, on a project whose merge queue tests several at once: a project made on queue v2 since 19 November 2026. A project that follows a GitHub repository, or whose checks run on GitHub, is made on the earlier queue, where depth changes nothing. It is a whole number from 1 to 20, and 16 when left out. A lower number takes fewer check machines at once and lands a long queue more slowly.

Pull requests on GitHub

[github]
pull_requests = "submitted"
queue_label = "switchyard"

pull_requests is "off" (the default), "submitted" or "all". When it is on, the project shows its tasks on GitHub as draft pull requests, keeps them in step as each task moves, and closes them when the task merges. queue_label names the label that puts a pull request on GitHub into the merge queue as a task: at most 50 characters, no commas, switchyard when left out. Connect a GitHub repository has the steps.

Next