FAQ & Troubleshooting

Organization mode: sign-in says the account is not a member of an allowed organization.

With GITDASH_ALLOWED_ORGS set, GitDash asks GitHub whether the account is an active member; if GitHub will not say, sign-in is refused and the server log shows GitHub's reason. Usual causes: the org has OAuth App access restrictions and has not approved the GitDash OAuth App (an org owner approves it under the org's Third-party access settings); a fine-grained PAT whose resource owner is the user instead of the org, or that lacks Members: read or is still awaiting org approval; a classic PAT without read:org, or one the org rejects for living longer than 366 days.

Organization mode: I was added to a group but still see the waiting page.

Group lookups are cached for 60 seconds. The waiting page checks every 15 seconds and moves on by itself once the grant is visible, so allow up to a minute. It also shows your GitHub login and numeric id to send to an admin.

I see a blank screen or 500 error after deploying.

Check that SESSION_SECRET is set and is at least 32 characters. The app throws at startup in production if it is missing or too short. Check server logs for [startup] errors.

Cost Analytics shows a 404 error about billing.

In org mode, Cost Analytics requires the GitHub Enhanced Billing Platform (Team or Enterprise). In standalone mode, only your personal billing data is available.

OAuth callback fails with 'state mismatch' or 'expired state'.

The sign-in cookie belongs to the host that started sign-in, so GitHub must send you back to that same host: if the app answers on several hosts (an apex domain, www, a *.vercel.app URL), start sign-in on the host in the OAuth App's callback URL, and redirect the others to it. State tokens also expire after 5 minutes — start again with Continue with GitHub if authorizing took longer.

DATABASE_URL is set but reports/alerts still don't work.

Confirm you are in MODE=organization. These features are disabled in standalone mode regardless of DATABASE_URL. Also check that ?sslmode=require is appended for Neon databases.

SESSION_SECRET must be at least 32 characters — but I'm running locally.

This check only applies when NODE_ENV=production. In development (pnpm run dev) any value is accepted.

How do I update to a new version?

Read the release notes first — some releases need new settings. Then pull the image (docker pull dinhdobathi/gitdash:latest, or a version tag) and restart; with Helm, upgrade the chart; self-built deployments pull the latest commit and rebuild. Database migrations run automatically on start.

Can I use a fine-grained PAT instead of a classic PAT?

Yes. Grant read access to Actions, Contents, Metadata and Pull requests on the repositories you want. A fine-grained token belongs to one resource owner: for an organization's repositories, create it with the organization as owner and add Members: read if sign-in is limited with GITDASH_ALLOWED_ORGS.

My organizations don't show up in the org switcher, even though I'm a member.

The switcher only lists what GitHub's orgs.listForAuthenticatedUser API returns for your current token — which depends on when that token was authorized, not just what orgs you belong to today:

Organization mode (OAuth): if you authorized GitDash before read:org was added to the requested scopes, your existing session won't have it. Sign out and sign back in to re-authorize with the current scope list.
Standalone mode (PAT): a classic PAT needs the read:org scope explicitly checked; a fine-grained PAT cannot see organization data at all (see the previous question).
Some orgs hide private membership from this API even with the right scope, depending on the org's own visibility settings.

In any case, you can still reach an org directly — type its name into the "Go to org by name" box in the org switcher, or open /org/<name> directly. Both work independently of the discovery list, using your token's actual repo access.