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.

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). 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.