Skip to content

Deploy GitMCloud

GitMCloud is a Vue + Vite single-page app hosted on Vercel, with serverless helper functions and a Firebase/Firestore backend for the Supplier Exchange feature. This page is for the publisher who owns the deployment.

This is an operational guide. For the code itself, see DEVELOPER.md in the GitMCloud repo.

What's involved

  • A Vercel project building the Vite app and auto-deploying from main.
  • A Firebase project with Firestore (for Supplier Exchange).
  • A GitHub OAuth App (enables "Sign in with GitHub"; PAT works without it) — see Register the GitHub apps.
  • The ALLOWED_OWNERS environment variable (the access allowlist).
  • A custom domain (gitmcloud.gojain.com).

1. Deploy on Vercel

  1. Import the GitMCloud GitHub repository into Vercel.
  2. Vercel detects Vite automatically. Build command: npm run build. Output: dist/.
  3. The serverless functions in api/ deploy automatically — they are plain .js (TypeScript Vercel functions fail at runtime here, so they're intentionally JS).
  4. Deploy. Every push to main redeploys automatically.

Hobby plan limit: Vercel Hobby allows a maximum of 12 serverless functions. GitMCloud ships exactly 12. Do not add a new api/*.js file without removing or merging one.

2. Set up Firebase (Supplier Exchange + realtime sync)

Create a Firebase project

  1. Go to console.firebase.google.com and create a project.
  2. Enable Firestore Database in Native mode.

Get the service account

  1. Firebase Console → Project Settings → Service Accounts.
  2. Click Generate new private key → download the JSON file.
  3. Stringify it to a single-line value: bash node -e "console.log(JSON.stringify(require('./serviceAccount.json')))"
  4. Add this value as the FIREBASE_SERVICE_ACCOUNT environment variable in Vercel (see below).
  5. Delete the downloaded JSON file — do not store or commit it.

Enable Realtime Database (required for live icon refresh in the GitM add-in)

  1. Firebase Console → Build → Realtime Database → Create Database.
  2. Choose any region and start in locked mode.
  3. Once created, go to the Rules tab and replace the content with the rules from database.rules.json in the GitMCloud repo root, then click Publish. These rules allow read/write only to the /repos/$hash/last_changed ping leaf.
  4. Copy the database URL shown at the top of the data panel (e.g. https://your-project-default-rtdb.firebaseio.com).
  5. Add this URL as VITE_FIREBASE_RTDB_URL in Vercel (see Environment Variables below) and redeploy GitMCloud.
  6. Add the same URL as RealtimeDbUrl in %APPDATA%\GitM\settings.json on each workstation only if it differs from the default (https://gitmcloud-default-rtdb.firebaseio.com). The GitM add-in ships with the correct default already baked in.

Enable Profiles and Messaging

Profiles and team messaging use Firebase Realtime Database. Two one-time activation steps are required after each rules change (the rules ship in database.rules.json in the GitMCloud repo root):

Step 1 — Set the Web API Key in Vercel

  1. Firebase Console → Project Settings → General → Your apps → Web API key.
  2. Copy the value (starts with AIza…).
  3. Add it as FIREBASE_WEB_API_KEY in Vercel → Environment Variables.
  4. Redeploy (this is a runtime variable, but it is read by the minter function at request time — a redeploy is safer than relying on cold-start timing).

FIREBASE_WEB_API_KEY is different from FIREBASE_SERVICE_ACCOUNT. The service account is already required for Supplier Exchange. The Web API key is additionally needed so the minter function can exchange a custom token for an ID token on behalf of the client.

Step 2 — Publish database.rules.json to Firebase

After any update to database.rules.json (it changed in Phases B, C, D, and D+):

  1. Open Firebase Console → Build → Realtime Database → Rules.
  2. Replace the content with the current database.rules.json from the GitMCloud repo root.
  3. Click Publish.

The rules extend the existing last_changed heartbeat section with: /users/{login} (profile data, write-gated to the owning login), /avatars/{login} (custom avatar base64, same gate), /userPrivate/{login} (email stored privately), /repos/{repoKey}/threads, /messages, /readState (messaging, gated to repo members).

If you skip this step, profile saves and all messaging will be silently rejected by the database security rules.

Set the Firestore TTL policy (prevents stale data)

  1. Firebase Console → Firestore → Indexes tab → TTL policies.
  2. Add: Collection shareThrottle, Field deleteAt.

This auto-deletes brute-force throttle records after 24 hours.

3. Set environment variables in Vercel

Vercel → your project → Settings → Environment Variables.

Required

Variable Value Notes
ALLOWED_OWNERS e.g. suchahit,acme-co Comma-separated GitHub org/user names. Empty → fail-closed (nobody connects).
FIREBASE_SERVICE_ACCOUNT Single-line JSON string From the Firebase service account key. Required for Supplier Exchange and brute-force throttle.
GITHUB_APP_ID Numeric App ID From the Exchange GitHub App settings page. Required for Supplier Exchange.
GITHUB_APP_CLIENT_ID Client ID (starts with Iv23…) From the Exchange GitHub App settings page.
GITHUB_APP_PRIVATE_KEY Full .pem contents Paste as-is including -----BEGIN/END----- lines. Vercel accepts multiline. Keep secret — never commit.

Optional

Variable Value Notes
FIREBASE_WEB_API_KEY Firebase Web API key (starts with AIza…) Required for Profiles and Messaging. Used server-side by the minter to exchange a custom token for an ID token via Identity Toolkit. See Enable Profiles and Messaging above.
VITE_GITHUB_CLIENT_ID OAuth App client ID Enables "Sign in with GitHub". Without it, PAT sign-in only. Requires redeploy (baked into bundle).
VITE_FIREBASE_RTDB_URL e.g. https://your-project-default-rtdb.firebaseio.com Enables live icon refresh in the GitM add-in after writes. Requires redeploy.
VITE_DOCS_URL e.g. https://gitmdocs.gojain.com Target of the in-app ? → Help link. Defaults to the current docs site if unset. Requires redeploy.
APS_CLIENT_ID APS app client ID Required for the Autodesk 3D viewer (not yet shipped).
APS_CLIENT_SECRET APS app client secret Required for the Autodesk 3D viewer (not yet shipped). Keep secret.

VITE_* variables are baked into the JavaScript bundle at build time — redeploy after changing them. All other variables are read at runtime and take effect on the next cold start with no redeploy needed.

4. Register the GitHub apps

The "Sign in with GitHub" Device Flow button needs a GitHub OAuth App. Supplier Exchange uses a GitHub App so customers install once and all their repos are covered. Both are registered once under the publisher account — see Register the GitHub apps. Without the OAuth App, PAT sign-in is still available.

5. Custom domain

  1. Vercel → project → Settings → Domains → Add gitmcloud.gojain.com.
  2. Create the DNS record Vercel shows (CNAME) at your DNS provider.
  3. Wait for DNS propagation and the automatic SSL certificate.

Set the access allowlist

Set ALLOWED_OWNERS (comma-separated GitHub org/user names) in Vercel. If it's empty, nobody can connect (fail-closed). See Manage the access allowlist.

Expected result

  • https://gitmcloud.gojain.com loads the app.
  • "Sign in with GitHub" appears if VITE_GITHUB_CLIENT_ID is set; otherwise PAT sign-in only.
  • Only allowlisted owners can connect.
  • Supplier Exchange works once FIREBASE_SERVICE_ACCOUNT and the three GITHUB_APP_* variables are set, and a customer has installed the Exchange GitHub App for their account (Settings → Exchange tab).

Troubleshooting

Symptom Cause Fix
FUNCTION_INVOCATION_FAILED on any API call A function was authored in TypeScript Vercel functions in api/ must be plain .js
"Sign in with GitHub" missing VITE_GITHUB_CLIENT_ID not set, or set after last build Add it and redeploy
Everyone is locked out ALLOWED_OWNERS empty/missing Set it; Vercel redeploys in ~30s
Env var change didn't take effect VITE_* vars are baked in at build time Redeploy after any VITE_* change
GitM icons don't refresh live VITE_FIREBASE_RTDB_URL missing or RTDB rules not published Add the env var, redeploy, and paste database.rules.json rules into Firebase console
Exchange: "not active" for all repos FIREBASE_SERVICE_ACCOUNT missing or malformed Paste the full single-line JSON value; check for truncation
Exchange: token validation fails Service PAT lacks contents:write on the repo Generate a new PAT with the correct scope

Known limitations

  • The allowlist is an environment variable; updating it triggers a redeploy (~30s). Instant updates via Vercel KV are planned but not shipped.
  • VITE_* variables are compiled into the bundle — they cannot be changed at runtime without a redeploy.

Moving to a new account

If the product moves to a company GitHub org, follow Migrate the publisher account — it covers re-registering the OAuth App, moving Vercel/Firebase, and updating every baked-in reference.