Skip to content

Register the GitHub apps

GitMCloud uses two GitHub integrations. Both are registered once under the publisher account and are independent of any customer.

Integration Status Purpose
GitHub OAuth App Shipped The "Sign in with GitHub" button (Device Flow)
Supplier Exchange GitHub App Shipped Lets anonymous suppliers download from private repos without a per-repo token

1. GitHub OAuth App

Enables the "Sign in with GitHub" Device Flow button. Without it, customers can still sign in with a Personal Access Token (PAT).

  1. GitHub → Settings → Developer settings → OAuth Apps → New OAuth App.
  2. Set:
  3. Application name: GitMCloud
  4. Homepage URL: https://gitmcloud.gojain.com
  5. Authorization callback URL: https://gitmcloud.gojain.com (Device Flow doesn't use a callback; any value works)
  6. Register and copy the Client ID. You do not need the client secret.
  7. Set VITE_GITHUB_CLIENT_ID in Vercel and redeploy (it's baked into the bundle at build time).

The client ID is embedded in the built JavaScript. That's expected and safe — Device Flow uses only the public client ID.

2. Supplier Exchange GitHub App

When a supplier opens a share link they are anonymous — no GitHub login. The Vercel serverless function must read the customer's (often private) repo on their behalf. The GitHub App provides a secure, per-customer credential that:

  • Is installed once per customer account — covers all their current and future repos.
  • Mints short-lived installation tokens on demand (≈1 hour); nothing long-lived is stored.
  • Requires no token pasting from customers — they click Install on GitHub's own screen.

One-time registration (publisher, once ever)

  1. GitHub → Settings → Developer settings → GitHub Apps → New GitHub App.
  2. Fill in:
  3. GitHub App name: GitMCloud Exchange
  4. Description: Enables GitMCloud to serve files from private repositories to suppliers via secure share links. Installed once per account — no per-repo setup required.
  5. Homepage URL: https://gitmcloud.gojain.com
  6. Callback URL / Identifying and authorizing users: leave blank / uncheck all.
  7. Webhook → Active: uncheck (no webhooks needed).
  8. Under Repository permissions set Contents → Read and write only. Leave everything else at No access. (Metadata: Read-only is mandatory and cannot be changed — ignore it.)
  9. Post installation → Setup URL: https://gitmcloud.gojain.com/api/exchange-setup
  10. Check Redirect on update — so re-configurations also trigger the callback.
  11. Where can this GitHub App be installed: Any account.
  12. Click Create GitHub App, then on the resulting page click Generate a private key → a .pem file downloads.

Vercel environment variables

Add these three variables in Vercel → Settings → Environment Variables. Do not redeploy after adding them — they are read at runtime, not baked into the bundle.

Variable Where to find it Notes
GITHUB_APP_ID Shown at the top of the App settings page (a number)
GITHUB_APP_CLIENT_ID Shown below App ID (starts with Iv23…)
GITHUB_APP_PRIVATE_KEY Full contents of the downloaded .pem file Paste as-is including -----BEGIN/END----- lines — Vercel accepts multiline values

Keep the .pem file secure. Delete it after pasting into Vercel or store it in a password manager. Never commit it to a repository.

What customers see

When a customer opens Settings → Exchange in GitMCloud they see an Install GitMCloud Exchange on GitHub → button. Clicking it takes them to GitHub's standard App install screen where they grant access to their repositories. After installing, GitHub redirects to the Setup URL above, GitMCloud stores the installation, and sharing is immediately available for every repo under that Owner — no further setup needed.

The per-repo access policy (which roles may create share links, native file allowance, password requirement, expiry caps) is set separately in each repo's Settings → Exchange tab and stored in .gitm/exchange-config.json. See Share files with suppliers.

Ownership note

Both apps are owned by the publisher GitHub account. Moving to a new account means re-registering them and updating the corresponding Vercel variables — see Migrate the publisher account.