for agents: this page is markdown at https://switch-yard.dev/docs/connect-github.md; every page is listed in llms.txt. copy page as markdown

Connect a GitHub repository

In this guide you will connect a GitHub repository to a Switchyard project so that GitHub keeps holding main and the merge queue merges there. You will finish with a project that follows the repository, a board for it, and agents able to start tasks on it.

Before you start

• You can administer the repository on GitHub, or an owner of its organization can.
• The repository has at least one commit on its default branch. Switchyard follows that branch; an empty repository has none.
• You are signed in to app.switch-yard.dev, and you are an owner or admin of the Switchyard organization that will own the project.

What following means

While a team onboards, the GitHub repository is the authority for main. Switchyard keeps its own copy and follows it: a merge moves the branch on GitHub first, through the Switchyard App, and only then moves Switchyard's copy, so Switchyard's main is never ahead of GitHub. A commit pushed straight to GitHub is picked up within seconds and kept; the next task merges on top of it. If GitHub is down, merges wait, and tasks keep working on Switchyard's copy. Making Switchyard the authority later, with GitHub as a mirror, is planned and not yet offered.

Step 1: install the Switchyard App

Open app.switch-yard.dev/projects/new. The first step sends you to GitHub to install the Switchyard App on your account or organization. GitHub lists what the App asks for before you agree. Choose which repositories it may reach; you can add more later from the same installation page on GitHub, which the set-up links to whenever a repository you expect is not in its list.

Step 2: choose the repository

The second step lists the repositories the App reaches that you can see on GitHub. If yours is missing, the page says why and links to the App's repository access; it reads the list again when you come back. An empty repository is shown greyed with the commands that make its first commit, and can be picked as soon as the branch exists.

A repository belongs to one project at a time. The set-up refuses a repository the App does not reach, one with no branch yet, one another project already follows (naming that project), and one you do not administer on GitHub, and says which.

Step 3: checks, rules and agents

The next steps set the checks the merge queue runs, the review rules, and the agents you use. By default both live in Switchyard, so nothing has to merge into the repository to begin; the rules and checks guide explains the file they produce. If you ask for them in the repository instead, Switchyard opens a pull request named .yard: Set up Switchyard that explains each change it makes and links back to these pages.

The set-up ends with the project's id, its board at https://app.switch-yard.dev/p/<project>, and an admin key shown once for scripts and agents that act as the project's admin. Keep it where you keep secrets; it is never shown again, and nothing in Switchyard will ever ask you to paste it into a chat.

From the terminal

From a clone, yard init --github owner/name creates the project when you are signed in with yard login --github and own or administer the organization; with several organizations, add --organization <slug>. --branch follows a branch other than the default and --name sets the display name. It refuses the same four cases the set-up page does, and says which.

What you have now

A project that follows your repository. Start a task with yard branch new, run an agent on it as the quickstart shows, and watch the merge land on GitHub. The project's settings page shows the connection, including what the App is allowed to do, and whether tasks appear as pull requests on GitHub; that is set by the [github] table in the rules file: off, when submitted, or every task.