Skip to content

Sign in and connect

GitMCloud opens with a short wizard: sign in to GitHub, pick a repository, choose a branch and display name, and connect. After that it remembers your connection.

Prerequisites

  • A GitHub account with access to the repository you want to view.
  • Your account (or the repo's owner) on the GitMCloud allowlist. If it isn't, the wizard blocks you at the access step — ask whoever runs GitMCloud to add it. See Manage the access allowlist.

Sign in

GitMCloud offers two ways to authenticate:

  • Sign in with GitHub (recommended) — uses GitHub's device flow: GitMCloud shows a short code and opens github.com/login/device; you enter the code and authorize. No password is typed into GitMCloud. (This button only appears if the deployment has an OAuth client ID configured — see Deploy GitMCloud.)
  • Personal Access Token (PAT) — paste a GitHub token instead. Always available, even without an OAuth app configured.

Your token is stored in the browser's localStorage and used only to call the GitHub API. It is never logged or sent anywhere except GitHub.

Connect to a repository

  1. Sign in.
  2. Pick the repository to view (one you have access to on GitHub).
  3. Choose the branch GitMCloud should read and, optionally, a display name for the project.
  4. GitMCloud runs the access check. If your owner is allowlisted, it connects; otherwise it blocks here.

Expected result

  • The dashboard opens on the Files tab, with Snapshots, BOM, Branch, and Team tabs available.
  • Your connection (owner, repo, branch, display name) is remembered, so reopening GitMCloud reconnects automatically — re-running the access check each time.

Settings

Click the gear icon (top-right of the dashboard) to open Settings. Changes here take effect immediately without re-running the wizard.

Connection tab

  • Display name — the label shown in the header for this repository.
  • Branch — switch which branch GitMCloud reads (same as the Branch tab → Switch).

Authentication tab

  • Shows which GitHub account is signed in.
  • Sign out — clears the stored token and returns to the wizard.
  • Sign in with GitHub / Enter PAT — re-authenticate without disconnecting from the repo.

Identity tab

  • Shows the signed-in GitHub username and avatar.
  • Useful to verify which account GitMCloud is using when you have multiple GitHub accounts.

Preferences tab

  • UI preferences (theme, display options).

Exchange tab

  • Supplier Exchange — install or remove the GitMCloud Exchange GitHub App for your account, and set the per-repo access policy. Requires Administrator role. See Share files with suppliers.
  • Shows Active when the app is installed for the account, or Not installed otherwise.

Diagnostics tab

  • Shows the raw connection state, stored token (last four characters), branch, and other debug information useful when reporting issues.

Troubleshooting

Symptom Cause Fix
No "Sign in with GitHub" button The deployment has no OAuth client ID configured Use the PAT option, or have the deployer set VITE_GITHUB_CLIENT_ID (Deploy GitMCloud)
Blocked at the access step Owner not allowlisted, or allowlist empty (fail-closed) Get added to ALLOWED_OWNERS (allowlist)
Repository not in the list Your GitHub account lacks access Get access to the repo on GitHub
Auto-reconnect suddenly fails Allowlist changed, or token expired Re-check the allowlist; sign in again
Settings gear not visible Not connected (wizard not complete) Complete the wizard first

Known limitations

  • The allowlist is fail-closed and checked on every reconnect. If ALLOWED_OWNERS is empty or your owner is removed, you lose access immediately.
  • Tokens live in browser localStorage; signing out or clearing site data removes them.