Open-source AI teammates in Slack, Teams, Discord, Telegram and Mattermost. Self-host it, with any agent harness and any model.
GitHub on a self-hosted server
People connect their GitHub account through a GitHub App the server's
operator creates, and grant agents repositories of the App's installations.
An agent's token is an installation token for exactly the repositories
granted, acting as the App, and lasts at most an hour. How it works is in
docs/design/service-connections-v2.md.
Without the App, GitHub is listed on the server as "GitHub is not set up on this server. Ask whoever runs your Switch server to add it under Connector apps in the Switch dashboard."
What you need
- The server's
GATEWAY_PUBLIC_URL, anhttps://address: GitHub sends each sign-in back to it. - A GitHub account or organization to own the App. An App owned by an organization keeps working when the person who created it leaves.
Create the App
In GitHub: Settings, Developer settings, GitHub Apps, New GitHub App (for an organization, under the organization's settings).
- Callback URL:
for example<GATEWAY_PUBLIC_URL>/gateway/provider-connections/github/callbackhttps://switch.example.com/gateway/provider-connections/github/callback. - Turn on Expire user authorization tokens. Switch keeps each person's sign-in fresh with its refresh token, and refuses a sign-in that does not expire.
- Under Repository permissions, set Contents and Pull requests to
Read and write (Metadata is read-only, and always on). These are the
most an agent's token can carry, as the catalog's
githubentry lists them; a read grant asks for read only. - Choose who can install it: only this account, or any account if people will install it on their own organizations.
- Create the App. On its settings page, generate a client secret and
generate a private key (a
.pemfile, downloaded once).
Give Switch the App
In Switch Console, open Admin in the sidebar and Connector apps under
Server, or in the Switch dashboard open Connectors beside Users. Both are
shown to the server's operator only, and only with the server's
service_connections flag on. Choose Set up GitHub. The dialog shows the
callback URL to register, with a copy button. Paste the App's Client ID
and Client secret, and choose the Private key file; it is read in your
browser and never shown. Then choose Check and save.
Switch asks GitHub first: it signs a request with the private key as the App named by the client ID, which proves the two belong to one App and tells Switch the App's name, so you never type it; and it tells a right client secret from a wrong one. Nothing is saved unless GitHub accepts all three. The secret and the key are stored encrypted, like every other stored credential (see key rotation), and the App is in use at once: nobody needs to restart anything. The card then shows the key's fingerprint, which matches the one GitHub lists under the App's private keys, and the App's install link to share.
People install the App on the accounts and repositories it may reach, then connect GitHub from Switch Console.
Rotating the secret or the key
Generate a new client secret or private key in the App's settings, then choose Update secret or private key on the card and enter only what changed. Nobody is disconnected: sign-ins belong to the App, not to its secret, and tokens already issued stay valid until they expire, within the hour. Once the card shows the new key's fingerprint, delete the old key at GitHub.
Replacing the App
Use a different app sets up another App, with another client ID. Everyone connected through the current App must connect again, and choose their repositories again too, since a grant names the old App's installations. The dialog says how many people in how many workspaces that is before anything changes, and their connections show as needing reconnection. Tokens already handed to agents stay valid at GitHub for up to an hour; if the old App's secret or key leaked, delete it at GitHub as well.
Remove leaves GitHub not set up: nobody can connect it, and the people connected lose it until an App is set up again. They can still disconnect.
Or, from configuration
The App can be set in the server's configuration instead:
GITHUB_APP_CONFIG_PATH: a JSON file withclient_id,client_secret,slug(the App's name in its URL) andorigin(the HTTPS address GitHub calls back; normallyGATEWAY_PUBLIC_URL);GITHUB_APP_PRIVATE_KEY_PATH: the private key's.pem, by absolute path.
With Helm, switchCore.githubConnectionsSecret holds github.json, and
switchCore.githubAppPrivateKeyPath names the key inside a mounted Secret.
The two are set together or not at all, and set but unusable, switch-core
does not start.
Configuration wins: while it is set, Switch uses it, an App saved in the
dashboard is ignored (switch-core says so at startup, and so does the card),
and saving from the dashboard is refused. The deprecated
HOSTED_GITHUB_CONFIG_PATH counts as configuration too; it names no private
key, so GitHub can be connected but not granted, and it can't be copied into
Switch. Unset it, restart, and set the App up from the dashboard instead.
To move a configured App into the dashboard, choose Manage it here
instead on its card: Copy into Switch saves the configured values with
nothing retyped, then remove the two variables (or the two Helm values) and
restart switch-core. It is the same App, so nobody reconnects. Copying is
refused while the file's origin differs from GATEWAY_PUBLIC_URL, since a
saved App is called back at GATEWAY_PUBLIC_URL.
An organization's own GitHub App
With the organization_connector_apps flag on (with service_connections),
an organization's admins can save its own under Organization,
Connectors in the dashboard, with the same callback, checks and
encryption as above. Every workspace in that organization then signs in
through the organization's App instead of the server's; the others keep
using the server's. If the organization's App stops working, its
workspaces see GitHub as unavailable, with the reason, rather than falling
back to the server's. Removing it sends them back to the server's App, and
people connected through it reconnect once. The flag is off by default.
Several replicas
Sign-ins in progress are kept in the database, and a change to the App reaches every switch-core replica within seconds; one that misses the news finds it within half a minute. Keep query strings out of every access log in front of the callback: its URL carries a single-use OAuth code.