Connect GitHub
The shared application that lets one of your users save their project into a repository of their own.
GitHub sign in gets somebody through the door. This application is for something else: it is what lets a user of your installation push a project into their own repository, without bringing their own GitHub application and without your installation holding admin rights over anybody's account.
Two names, GITHUB_CONNECT_CLIENT_ID and GITHUB_CONNECT_CLIENT_SECRET, and they are read by the app,
not by the deployment.
One application serves everybody
A user pressing Connect GitHub is sent through the same application, and
the token that comes back is theirs: it is sealed with the installation's
SETTINGS_SECRET and it is only ever used for that account's projects. Nobody
else can use it, including you, and the vault never shows it to anybody,
including to the owner of the installation.
Creating it
A second OAuth application
GitHub, Settings → Developer settings → OAuth Apps → New OAuth App. Yes, a second one, alongside the sign-in application. Keep the names honest, for example Your Product connect, so that the two are distinguishable in the list a year from now.
The callback belongs to the app, not the deployment
| Field | What to put |
|---|---|
| Homepage URL | Your app's address |
| Authorization callback URL | https://loomis.your-domain.com/api/connect/github/callback |
For a laptop: http://localhost:3000/api/connect/github/callback.
Note the difference from sign in: the path is /api/connect/github/callback, not
/api/auth/callback/github. The first is served by the app, the second by the deployment.
Set them where the app can read them
# in .env.local
GITHUB_CONNECT_CLIENT_ID=Iv1.0123456789abcdef
GITHUB_CONNECT_CLIENT_SECRET=your-secretOr run pnpm configure --only=app and answer those two, which keeps the file and its backup tidy.
Restart the app afterwards: these are read when the process starts.
Confirm it is offered
In the product, open the Connectors tab and look at the GitHub card. Configured, it offers to connect. Unconfigured, the card says so instead of offering a button that fails.
In the panel, Platform → Integrations is the same question asked from the other side: which integrations
this installation can offer at all.
What a connected account can then do
| Action | Where the user does it |
|---|---|
| Save a project to a repository | The GitHub card beside the code workbench, or the deploy panel |
| Choose an existing repository | The same card, listing what the account can push to |
| Deploy from a repository | The deploy panel, after the repository is attached |
| Disconnect | The Connectors screen, which deletes the sealed token |
The scopes it asks for
The authorisation asks for the ability to read the account's profile, list its repositories and write to a repository it is given. It is not asked for, and cannot be used for, anything administrative: no organisation settings, no billing, no access to repositories the person has not chosen.
What to tell your users
Connecting GitHub means this installation will hold a token that can write to the repositories it is given. That token is sealed with the installation's own key, it is never displayed, and disconnecting deletes it. A user who wants none of that can ignore the card entirely: nothing else in the product needs it.