Connect a repository

Connecting a repository tells Orbi which repository’s Issues it may work on, and which branch to open pull requests against. Connecting is self-service: you pick the repository and the base branch on the connect page, and Orbi starts preparing the work environment right away. Connecting does not create any Issue in your repository. How many repositories can be connected at the same time depends on your plan: one on Free and Solo, up to five on Pro. Changing one always means disconnecting it first. See limits and quotas.

​

Connect

On first setup, with no repository connected, if your App installation covers exactly one repository and it is unarchived with Issues enabled, it connects automatically on its default branch. The selection form is skipped. If the selection form appears, use it to choose the repository and base branch. Before you have connected anything, the main status card on the status page says Connect a GitHub repository first; click Connect repository. Once you have a repository, click Manage projects in the top right of the project overview on the status page, which opens the same page.

1. Repository: pick from the repositories your GitHub App installation covers. With more than 8 repositories, a Search repositories box appears; type part of the name to filter the list.
2. Base branch: the branch Orbi opens pull requests against. Selecting a repository loads its real branches and preselects its default branch, so usually you just confirm. Only existing branches can be selected. If the branch list cannot be read, refresh and retry; the connect button is unavailable until it can be verified.
3. Click Connect repository. The button changes to Connecting… while it works; you do not need to click again.

Connecting opens that project’s status page and starts preparing the work environment. Once ready, Orbi reads the repository and suggests work. Open Review draft for a new task and confirm before handing it off. You can still write your own request or create an Issue with ai-ready on GitHub. To try a small project in your own GitHub account, open No suitable repository yet? Create one from Orbi’s sample on the connect page and follow Open the sample template ↗. One verified official example copy can be connected alongside your real projects on every plan. It does not use a repository slot or your free deliveries. An arbitrary repository with a similar name does not qualify; see the example walkthrough.

​

Requirements a repository has to meet

A repository can only be connected if:

• It is covered by your GitHub App installation. Orbi only sees repositories you authorized.
• It has Issues enabled. Orbi receives tasks through Issues, so the list marks such a repository (Issues disabled; enable them first), selecting it shows a link to the repository settings, and connecting it is rejected. Enable Issues under the repository’s Settings → Features first.
• It is not archived. Archived repositories are left out of the list.

Repositories that are already connected are left out of the list too. When you submit, Orbi checks again that the repository is still covered by the installation and has Issues enabled, so a repository that was de-authorized in between is caught.

​

When your repository is not listed

The list only contains repositories your App installation covers. If yours is missing, open Don’t see your repository? on the connect page:

• If you selected only some repositories when installing the App, follow the GitHub App settings link, add the repository under Repository access, click Save, then come back and refresh.
• If the repository belongs to an organization, choose that organization on the installation page; if you are not an organization administrator, ask an administrator to install or approve it.

If GitHub’s repository list cannot be read, the page offers a field for owner/repository. This degraded form uses main as the base branch and still verifies access and branch existence before connecting. It has no free-text branch field. For a different branch, retry the normal selector when GitHub is available.

​

Branch protection that blocks every merge

If your base branch requires approving reviews before merge, this setting stops every task at the merge step. The reason is identity: Orbi opens the pull request and merges it as the same GitHub App, and GitHub does not let a pull request’s author approve their own pull request. With required approvals in force, each task gets as far as a checked, ready pull request and then cannot merge it. On the status page, the headline then reads You need to approve this change on GitHub, and the task’s status shows Awaiting approval. Before you hand off a request, the write-a-request page says Your repository requires an approval before merging, so you know Orbi will wait for you. Choose how your repository should handle approvals:

1. Keep a human approval. A reviewer other than the PR author approves on GitHub. Orbi can then merge when the remaining conditions pass.
2. Configure a bypass for the actual merging actor, when your repository policy permits it. In Settings → Rules → Rulesets, an administrator can add the installed Orbi GitHub App to the relevant rule’s bypass list. Giving a personal administrator account bypass does not give the App bypass. See GitHub’s bypass instructions.
3. Remove the required-approval rule if your policy allows merges after Orbi’s independent review and CI alone.

Only a repository administrator can change these rules. Reconnecting Orbi is unnecessary. Other applicable branch rules and rulesets still apply.

​

More than one repository

On a plan that allows several repositories, click Manage projects on the status page. The connect page shows how many you have used against your limit (for example Used 1 / limit 5 repositories) and lists the connected ones under Connected; pick another repository and click Connect repository. Adding one does not affect the repositories already connected, and each repository gets its own work environment, prepared separately. The status page’s Project section has one summary row per project; Manage projects shows the count and limit. With several projects, the overview does not combine their task tables. Click a row for that project’s base branch, current status, task history and versions. Versions are available on Free too. The suggestion area switches between All and individual projects. See the status page.

​

Changing the base branch

Open Manage projects, find the connected repository and click Change base branch. Pick an existing branch from Base branch, then Save base branch. You do not need to disconnect the repository. If GitHub’s branch list cannot be read, refresh and retry; a name that has not been verified cannot be saved. If an Issue was blocked specifically because the old base branch did not exist, correcting the branch queues that Issue again automatically, usually within 1–2 minutes. You do not need to change its labels. A different blocked reason still needs its own repair.

​

Changing the connected repository

There is one rule on every plan: disconnect the repository you are leaving, then connect the new one. Connecting never replaces a repository on its own.

1. Click Manage projects. Under Connected, click Disconnect… on the repository you are leaving, then Confirm disconnect.
2. Pick the new repository and click Connect repository.

Disconnecting reclaims that repository’s work environment. It does not change the repository on GitHub, and your history and usage are kept: the repository appears under Disconnected projects in Usage and settings on the status page. Connecting it again later prepares a fresh work environment, which usually takes 10–20 seconds, like any new repository. When you are already at your plan’s limit, the connect page is titled Repository limit reached: it has no connect form, only your connected repositories, each with Disconnect…. The exception is a sample copy you just created: it does not count toward the limit, so the page shows Connect the sample copy you just created with a Connect sample copy button, and you do not need to disconnect anything first. If a connect request is refused for the same reason, the error page offers Disconnect a repository, plus an upgrade to Pro on a plan below Pro.

​

What the errors mean

​

What happens next

After you connect, Orbi prepares the work environment: it builds the isolated environment your tasks run in and installs the ai-* labels into your repository. When Prepare work environment is done, write your first request, or hand Orbi one of your existing Issues.