Where to start it
You can start from any of these places. Each opens the same GitHub screen.
A new factory's Work page. Step 1 of the setup panel starts the connection.
1
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.
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.A GitHub installation belongs to one OuterLayer organization. If another OuterLayer organization already connected it, the connect fails and a page says the installation is already in use. Ask that organization to remove it, or install on a different GitHub organization.
2
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 context source reads them from that source instead.3
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.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.Each repository carries its own agent instructions and policy. Where several should share one set, one repository can be the factory’s context source and supply them to the rest. You don’t need one to start: see Share instructions across repositories.
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.What the connection is used for
The evidence comment
The docs call it the evidence comment. The setting that turns it on is Post session summaries on pull requests, on Settings → General. It is 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.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.
On the Factories page, the card menu shows Connect Git Repository until the App is installed. After that it shows Link repository, and once a repository is linked, Change Git Provider.
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.