Where to start it
You can start from any of these places. Each opens the same GitHub screen.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.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.
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 control plane 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.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.
Repositories from more than one GitHub organization
A factory can link repositories from several GitHub organizations, for exampleacme 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. 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 isDELETE /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 underunreachable. 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. 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.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. 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.
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 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.
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.