# GitHub connector

> GitHub is a workspace install made by an owner or admin. They install the Bolter GitHub App on an account and choose repositories; there is no personal link.

GitHub is connected at the workspace level only. A workspace owner or admin
installs the Bolter GitHub App on a GitHub account or GitHub organization and
chooses which repositories it covers. There is no personal GitHub link.

## Installing

The install starts from the workspace's Integrations tab, or from the card
an agent posts when it requests GitHub access that is not connected yet. The
admin signs in with GitHub, picks the account or GitHub organization, and
either installs fresh or attaches an installation that already exists. The
person completing it must actually manage that installation on the GitHub
side.

## A custom GitHub App

Everything an agent writes on GitHub through the standard connection appears
under Bolter's GitHub login. If an agent should write under a bot name of
your own, open the GitHub connection you already have under Connected and
choose "Add a custom GitHub App" below it. Create a GitHub App under the
GitHub account that owns the repositories the agent should write to,
give it the callback URL the form shows as both its callback and setup
URL, turn on "Request user authorization (OAuth) during installation",
and paste its App ID, slug, client ID, client secret and private key. The
secret and key are stored encrypted and never shown again; pasting the same
app again replaces them, which is how you rotate a key. The install then
works the same way as "Link GitHub": when GitHub asks where to install,
pick the same account, and the result is a second connection listed as
"GitHub (your app's slug)" with the account name.

An agent never picks that connection up on its own: when it asks for GitHub
access it is offered the standard connection. A workspace owner or admin
gives the custom one to an agent by granting it from the agent's Credentials
tab, and the agent can then use it from any of its computers, including for
several of your apps at once. Every other agent keeps using the standard
connection.

## Repository choice

The install can cover all repositories or a selected list. If an agent later
needs a repository the installation does not cover, the admin widens the
installation on GitHub first, then approves the grant.

## If a repository is renamed

A grant names a repository by its `owner/name` slug, and GitHub does not
follow renames when it issues the short lived tokens agents use. So a grant
approved before a rename stops working, even though the repository is still
there and the install still covers it.

The agent will tell you the repository was renamed and name the current one.
It cannot repoint the grant itself, because that would widen what you
approved without asking. Either edit the grant's repository list on the
agent's Credentials tab, which keeps the permissions you already approved, or
approve the fresh request the agent raises. Editing is usually the better
option: a new request may ask for less than the old grant had.

## If access stops working: re-verification

Bolter periodically re-checks that the person who linked the connection still
administers the installation on GitHub. If that check stops passing, because
they left the GitHub account, lost admin rights there, or revoked Bolter's
GitHub sign-in, the connection is marked as needing re-verification and no
further tokens are issued against it.

Nothing is wrong with the grants themselves when this happens. Requesting a
new grant, widening an existing one, or revoking and re-requesting will all
fail the same way, and revoking loses access that is otherwise fine.

The check keeps running while the connection is paused, so if the underlying
problem is fixed on GitHub, for example the person gets their admin rights
back, the connection clears itself within a minute of the next attempt and
nobody has to press Re-verify. Re-verify is for the case where that is not
going to happen and somebody else needs to take the connection over.

Every workspace owner and admin gets a notification the moment this happens,
and, while anything is still trying to use the connection, another at most
once every six hours, so a problem nobody picked up on the first day does not
go quiet. A connection nothing is using stays quiet after the first
notification, because the check only runs when something asks for access. The standing
signal is the connection's card in the workspace's Integrations tab, which
carries a "Re-verification required" badge until somebody acts. The badge
clears itself when the connection clears itself.

A workspace owner or admin fixes it in one place: open the workspace's
Integrations tab, select the GitHub connection, then Re-verify. Whoever
completes it signs in with a GitHub account that administers the installation.
That can be a different person from the one who linked it originally.

Agents blocked this way will say the connection needs re-verifying and stop
retrying. They cannot fix it themselves.

## Grants

As with every connector, installing gives no agent access by itself (see
[Connectors overview](https://bolter.chat/help/connectors/index)). An agent requests a credential grant scoped to
specific repositories, and a workspace owner or admin approves it on the
request card. Agents then work with those
repositories using short lived, repository scoped access.

## How the access is handled

When an agent reads or writes GitHub, Bolter attaches the credential on the
server on its way out. The agent does not hold it, and it does not appear in
the chat or in anything the agent writes down. Code an agent builds in a
computer works the same way: it names the grant, and Bolter fills in the
credential as the request leaves.

Pushing commits over git is the one case that still needs the agent to hold a
short lived token, because git has to present the credential itself.

## A grant that names no repositories

An agent can request GitHub access before anything is connected, at which
point there is no installation to pick repositories from, so the request
carries permissions only. A grant approved in that state covers no
repositories and no work can run against it. The agent will come back with a
second request naming the repositories it needs once the install exists.
Approve that one too, or edit the first grant's repository list on the
agent's Credentials tab.

Source: https://bolter.chat/help/connectors/github_app