switchyard

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

Connect a GitHub repository

Connect a GitHub repository so that agents start tasks on its main and the merge queue merges their work there.

You will have: a project that follows your-org/your-repo, with its board at https://app.switchyard.so/p/your-project. Works with: the board (set-up page), yard (yard init), REST. MCP cannot create a project. Takes: about 5 minutes.

GitHub keeps holding main. How a project follows a repository is on the architecture page. What happens while GitHub does not answer is on the outages page.

Before you start

Step 1 — Open the set-up page

Open the set-up page. It shows five steps: connect GitHub, choose a repository, agents, set up and first task. When hosted Switchyard requires a card, a card and plan step comes before first task.

https://app.switchyard.so/onboarding

The page is titled set up a repository. You are on the connect GitHub step.

Step 2 — Install the Switchyard App

Install the Switchyard App so that Switchyard can read the repository and merge into it.

Click install the app on GitHub ↗. On GitHub, choose your account or organization, and then choose the repositories the App may reach. GitHub shows what the App asks for. If you cannot install apps on the GitHub organization, an owner of that organization installs it.

Come back to the set-up page. The page reads the App's installations again. When the App has one installation, the page goes to the next step by itself.

The App is installed. Next, you choose the repository.

Step 3 — Choose the repository

Click the repository in the list. The list shows only the repositories the App may reach. When a repository is missing, the link under the list opens the installation on GitHub, where you give the App more repositories.

The page refuses some repositories and shows the reason beside each one:

ReasonMessage
archived<repo> is archived on GitHub, so nothing can merge on it; unarchive it first
disabledGitHub has disabled <repo>
no commit<repo> has no commits on <branch> yet; push a first commit on GitHub, then come back
too large<repo> is <size> GB on GitHub; Switchyard takes repositories up to 8 GB for now
not an adminyou can write to <repo> but are not an admin of it on GitHub; ... (or the read-only or no-access form)
followeda project of another team already follows <repo>

One repository belongs to one project at a time. The plan's own size limit is checked when the project is created, in Step 6.

You have chosen the repository. Next, you read what Switchyard drafted from it.

Step 4 — Check the drafted checks and rules

Switchyard reads the repository and drafts checks and rules. One line sums them up, for example:

checks: npm test · rules: 3, merge when checks pass

Click change to edit the draft. You can turn a check off, add a check (+ add a check), choose whether a person approves changes, and choose each rule's outcome. A CI job that regenerates code and then checks that the result is committed becomes a check named generated files are current. Write rules and checks explains the file.

The checks and rules are ready. Next, you choose the agents.

Step 5 — Choose the agents

Choose the agents you use. Switchyard writes their set-up files only when the checks and rules live in the repository (Step 6).

By default, an agent submits its task when the work is done. To make a person submit each task from the board, open more options and choose a person submits each task from the board; agents only push. This choice is the project's who-submits setting.

Step 6 — Set up the project

Choose where the checks and rules live:

Click set up your-org/your-repo. The page shows the project's id and the project's admin key.

Warning: The admin key is shown one time only. Copy it to where you keep secrets before you leave the page.

The project exists. The first task step shows the board link and the commands to start a task.

When main is protected

When GitHub protects main with rules that ask for pull requests, approvals or status checks, the merge queue merges each tested batch through a pull request. Switchyard opens one pull request for each batch, on a branch named switchyard/land/<commit>, at the commit that passed the checks. Switchyard then asks GitHub to merge that exact commit and waits while GitHub's rules hold it. An approval that GitHub requires still waits for a person on GitHub.

The merge method follows GitHub's rules. Switchyard uses a merge commit, or a rebase when the rules require linear history. Switchyard uses a squash only when nothing else is allowed.

The merge record keeps the tested commit and the commit that GitHub made. yard verify <commit> checks that the commit on main has the tested tree.

When main requires the switchyard check, set the check's source to the Switchyard app. Then a check of the same name from another app, or from a workflow, cannot satisfy the rule:

Do the same for each of your own required checks: GitHub Actions for a workflow's job, or the app of your CI provider.

To let Switchyard push tested work straight to main:

  1. Open the branch's ruleset on GitHub.
  2. Add the Switchyard App as a bypass actor.

Switchyard tries a direct push once a day, and pushes straight from the first time GitHub accepts it. Switchyard does not use GitHub's merge queue, so a main that requires GitHub's merge queue needs the bypass actor.

Pull requests that become tasks

A pull request on the followed repository can go through the merge queue like a task: add the label switchyard to it. Pull requests in the merge queue says what happens next, what the status comment and the switchyard queue check on the pull request show, and why switchyard queue is never a check to require.

To show tasks as draft pull requests on GitHub, set pull_requests in the [github] table of the rules file.

From the terminal

Create the project from a clone of the repository, signed in with yard login https://app.switchyard.so --github.

yard init --github your-org/your-repo

yard init creates the project in the organization you own or administer. The project's id is the value of --project, or else the directory's name. yard saves the project and its admin key in .git/yard.json and does not print the key.

yard init refuses a repository you do not administer on GitHub, one larger than your plan takes, and one that another project follows. Unlike the set-up page, yard init does not refuse an archived or disabled repository. The CLI page lists every flag. REST: POST /v1/projects (the REST API page has the body).

Verify

Open the project's settings page on the board. The GitHub connection section shows the repository, the installation, the last push and the App's permissions and events, each marked ✓ or ✗.

Next