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
- You are an owner or admin of the Switchyard organization that will own the project.
- You are an admin of the repository on GitHub.
- The repository has at least one commit on its default branch.
- The repository is not larger than your plan takes (limits).
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:
| Reason | Message |
|---|---|
| archived | <repo> is archived on GitHub, so nothing can merge on it; unarchive it first |
| disabled | GitHub 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 admin | you can write to <repo> but are not an admin of it on GitHub; ... (or the read-only or no-access form) |
| followed | a 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:
- in Switchyard (recommended): they apply at once, and nothing merges into the repository.
- in the repository: Switchyard writes
.yard/rules.tomland the agents' set-up files. Choose commit it for me (recommended) to commit them to main at once, or open a pull request for me to review and merge. The pull request is named.yard: Set up Switchyard. When main is protected, Switchyard opens the pull request.
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:
- Rulesets: open the ruleset. Under Require status checks to pass, find the
switchyardcheck and set its source to the Switchyard app. - Branch protection rules: open the rule for main. Under Require status checks to pass before merging, find
switchyardand choose the Switchyard app as its source.
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:
- Open the branch's ruleset on GitHub.
- 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.
--organization <slug>chooses the organization when you belong to more than one.--branch <branch>follows a branch other than the default branch.--name <name>sets the display name.
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
- Quickstart: start a task and run an agent in it.
- Write rules and checks: the checks the merge queue runs.
- Review a change: approve what the rules send to a person.