> ## Documentation Index
> Fetch the complete documentation index at: https://docs-stg.outerlayer.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect a repository

> Install the OuterLayer GitHub App, then link a repository and its base branch to the factory.

A factory reads its issues, pull requests and check results from GitHub. Until a repository is connected, nothing can be added to the Work page.

Connecting has two steps. Install the OuterLayer GitHub App on your GitHub organization. Then link a repository and its base branch to this factory.

## Where to start it

You can start from any of these places. Each opens the same GitHub screen.

| Where | What you choose |
| - | - |
| The setup panel, on a new factory's Work page | **Connect GitHub repository** on step 1 |
| The factory's **Settings → General** | **Connect GitHub repository**, offered while no repository is connected |

On **Settings → General**, the **Repositories** section shows **Connect GitHub repository** until the App is installed. After that it shows **Link repository**. Each linked repository has its own **Unlink** button. Unlinking the factory's control plane repository also removes the factory's control plane. For what happens to work items, see [Work items in an unlinked repository](#work-items-in-an-unlinked-repository).

<Steps>
  <Step title="Install the App on GitHub">
    GitHub asks which organization to install on, and whether to grant all repositories or only selected ones. Grant at least the repository you mean to link. You can change the grant later on GitHub.

    An owner of the GitHub organization installs the App. Any other member can pick the organization and request the install. GitHub sends the request to the owners, and the install completes once one of them approves. A repository under your own account needs nothing extra.

    <Note>
      A second factory, or another repository, reuses the organization's installation. Start the connect from the factory, and save on GitHub within 10 minutes. See [Repositories and factories](#repositories-and-factories).
    </Note>
  </Step>

  <Step title="Link a repository and its base branch">
    GitHub returns you to where you started, and the same place now offers **Link repository**. Choose it, then pick the repository and its base branch.

    Pick the branch your pull requests merge into. Policy and validators are read from `.outerlayer/` on each pull request's base branch. A repository governed by a [control plane](/share-instructions-across-repositories) reads them from that source instead.
  </Step>

  <Step title="Confirm">
    The repository's open issues now appear in **Add work** on the Work page. A pull request opened from a session on one of its items is joined to that item.

    To link the next repository, see [Repositories and factories](#repositories-and-factories).
  </Step>
</Steps>

## Repositories and factories

A factory can hold several repositories. Link the next one from **Settings → General**, which lists each with its branch. A repository on a GitHub organization without the App needs the install first. One on an organization already covered needs only the link.

Create a second factory only when a group of repositories needs its own Work page, its own keys and its own policy.

A repository belongs to one factory in an organization. A pull request gets one OuterLayer check, so only one factory's policy can apply to it. Linking a repository that another factory already has is refused, and the message names that factory. Unlink it there first.

A repository linked to two factories before this rule keeps both links. **Settings → General** shows a notice on it naming the other factory, with a link to that factory's settings. Unlink it from one of them.

Each repository carries its own agent instructions and policy. Where several should share one set, one repository can be the factory's **control plane** and supply them to the rest. You don't need one to start: see [Share instructions across repositories](/share-instructions-across-repositories).

### One installation for every factory

Every factory in an organization can use that organization's one GitHub App installation. Connecting a second factory, or choosing another repository, reuses that installation. GitHub opens its settings, and saving them returns you to the factory you started from. Start the connect from the factory itself, and save on GitHub within 10 minutes of starting it.

A repository the installation does not cover yet is added from the App's settings on GitHub, under **Settings → Applications → Installed GitHub Apps → OuterLayer → Configure**. Then link it from the factory.

One GitHub App installation can connect to more than one OuterLayer organization. If another organization already connected your GitHub account, connect from your factory as usual. GitHub asks you to authorize, and the connect completes once GitHub confirms you can access the installation. The other organization keeps its connection, and neither organization sees the other's.

## Repositories from more than one GitHub organization

A factory can link repositories from several GitHub organizations, for example `acme` and `acme-labs`. The GitHub App is installed once on each organization, and the factory keeps one installation per organization. Each repository is reached through the installation that covers its own organization, so a build in `acme-labs/api` never uses the `acme` installation. The Work list, the policy and the ledger stay in one factory.

On **Settings → General**, the **Repositories** section shows one header row for each organization that has a linked repository. The row shows the organization's name, how many repositories are linked from it, and **Remove organization**.

### Add an organization

Choose **Add GitHub organization**, beside **Link repository**. GitHub opens its account picker. Install the App on the next organization. OuterLayer returns you to **Settings → General** with the **Link repository** dialog open on that organization, and the organization's other repositories listed first. The installations the factory already holds are unchanged.

If you choose an organization the factory already holds, nothing changes, and the dialog says so. If you gave the App access to more repositories on GitHub, they are listed now.

If you are not an owner of the organization, GitHub sends the request to its owners. **Settings → General** then shows a notice, **Waiting on an owner**, and the other organizations keep working. After an owner approves, choose **Add GitHub organization** again to connect it. **Dismiss** hides the notice for everyone in the factory.

### Remove an organization

**Remove organization** opens a dialog that lists the repositories it unlinks, with their branches and pull-request comment settings. Type the organization's name to confirm. Work items on those repositories keep their history. See [Work items in an unlinked repository](#work-items-in-an-unlinked-repository).

**Remove organization** removes the organization from this factory only and does not uninstall the App on GitHub. It does not touch another factory or another OuterLayer organization that uses the same installation. To uninstall the App, open the installation on GitHub from the link in the dialog.

If the organization holds the factory's control plane, the dialog says which repository becomes the default control plane. It suggests naming a control plane in another organization first. The API route is `DELETE /v1/apps/{appId}/installations/{installationId}`, and it needs the delete permission on git.

Unlinking the last repository of an organization removes the repository only. The organization leaves the list, and its installation stays connected, so its repositories are still offered under **Link repository** without a reinstall.

### If the App is suspended or uninstalled on an organization

* **Suspended.** An owner of the organization suspended the App on GitHub. The organization's header row shows **Suspended on GitHub**, with **Open on GitHub**. Its repositories stay linked, but OuterLayer cannot read or push to them, so builds of items in those repositories fail before they start, with `repository_not_reachable`. A build of an item in another organization still starts: the claim leaves the suspended organization's repositories out and lists them under `unreachable`. They work again once an owner unsuspends the App.
* **Uninstalled.** An owner removed the App on GitHub. OuterLayer unlinks that organization's repositories from every factory that held the installation, and a notice above the Repositories list names the organization and the repositories. Work items on them keep their history. See [Work items in an unlinked repository](#work-items-in-an-unlinked-repository). The **Reinstall** button for that organization opens the install page again. Other organizations are not affected.

## Issues in Linear or Jira

The repository connection reads GitHub issues. If your team's issues live in Linear or Jira, also connect that tracker on **Settings → Issue tracker**. Its issues then appear in **Add work** beside the GitHub ones. You still need the repository connection, because pull requests, checks and policy come from GitHub. See [Connect an issue tracker](/connect-a-tracker).

## What the connection is used for

| Signal | Where it comes from |
| - | - |
| Issues for the Work page | Read from the repository when you add one. |
| Pull request state and check results | GitHub tells OuterLayer as they change. |
| Policy and validators | `.outerlayer/policy.yaml` and `.outerlayer/validators/` on the pull request's base branch. |
| Repository tokens for builds | The gateway asks GitHub for a token limited to one repository. See [GitHub App permissions and build tokens](/github-app-and-build-tokens). |
| The evidence comment | Posted on each pull request. See below. |

### The evidence comment

The setting that turns it on is **Post session summaries on pull requests**, on **Settings → General**. Each linked GitHub repository has its own switch, off by default.

The comment lists the checks on the pull request and the agent sessions behind it. It includes each session's duration and cost. On a public repository, anyone can read it, costs included. Turning the setting off stops new comments; a comment already posted stays.

## Work items in an unlinked repository

Unlinking a repository changes no work item and no pull request. The factory stops receiving updates from that repository, so its pull requests stay open in the factory.

A work item with an open pull request in an unlinked repository shows **Repository disconnected**. The chip sits beside the status in the item's header. The **Activity** tab opens with a note. The note names the repository and its pull request. The Work list shows **Repository disconnected: owner/repository** on the item's row. `outerlayer work status` prints a line that names the pull request and says how to connect the repository again or remove the item.

While the repository is unlinked, the factory cannot build, amend or check the item. A build request for it stops with `pull_request_repository_not_connected`.

Choose one of two ways out:

* **Reconnect the repository.** Choose **Reconnect repository** in the note. It opens **Settings → General**, where you choose **Link repository**. The status clears with no other step. The item returns as it was.
* **Remove the item from Work.** Run `outerlayer work remove --item <number>`. The note shows the command with the item's number.

Pull requests that merged or closed before the unlink do not count. An item with only those does not show **Repository disconnected**.

## If GitHub returns an error

When OuterLayer cannot finish a connect, you stay signed in and land on a page that says what failed. Its **Go back** button returns you to the page where you started the connect. If that page is not known, it goes to the factory's **Work** page. If OuterLayer cannot tell which factory the connect was for, it goes to your organizations list.

| Message | What it means | What to do |
| - | - | - |
| **GitHub connection could not be confirmed** | The link back from GitHub is missing, expired or not valid. An interrupted attempt, or one left open too long, cannot be resumed. | Connect again from the factory: the setup panel or **Settings → General**. |
| **GitHub's answer was incomplete** | GitHub returned without saying which installation to connect. | Connect again from the factory. |
| **GitHub installation could not be confirmed** | GitHub did not confirm that you can use the installation. The sign-in on GitHub may be a different account from the one that owns it, the link was already used, or GitHub sent no authorization for an installation another organization already uses. | Connect again from the factory, signed in to GitHub as a member of the account that owns the installation. |

If a connect fails a second time, the App may have been removed on GitHub. Start the connect again, and GitHub offers the install. Then link the repository again.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.