Skip to content

docs: Enhance GitHub Sign-In setup, customizations, and troubleshooting#521

Draft
Zfinix wants to merge 3 commits into
mainfrom
chore/update-sign-in-with-github-docs
Draft

docs: Enhance GitHub Sign-In setup, customizations, and troubleshooting#521
Zfinix wants to merge 3 commits into
mainfrom
chore/update-sign-in-with-github-docs

Conversation

@Zfinix
Copy link
Copy Markdown
Contributor

@Zfinix Zfinix commented May 18, 2026

Problem

The Sign in with GitHub docs lagged behind Google and Apple in structure and depth: no Prerequisites section, title-case headings inconsistent with sibling providers, no production deployment guidance, no troubleshooting page, stale screenshots, and a thin customizations page missing the server-side API hook, global auth user hooks, and parameter reference. The Web flow also predated the new FlutterWebAuth2CallbackRoute and relied on a manually-created auth.html even when Serverpod could serve the callback itself.

Solution

  • Setup page -- Added Prerequisites, sentence-case headings, and a ## Publishing to production section with self-hosted and Serverpod Cloud (scloud password set) paths. Web flow refactored into Serverpod-hosted (using pod.configureFlutterWebAuth2CallbackRoute() and /auth/callback) and separately-hosted (static auth.html) sub-paths. Five new screenshots replace the stale set.
  • Customizations page -- Renamed from 02-configuration.md to 02-customizations.md for parity with Google. Added GitHubIdpConfig vs GitHubIdpConfigFromPasswords intro, manual credential loading, server-side API access via getExtraGitHubInfoCallback, global onBeforeAuthUserCreated / onAfterAuthUserCreated hooks, and a parameter reference table.
  • Troubleshooting page (new) -- Setup checklist and 11 scenarios covering redirect_uri_mismatch, callback handling for both web flows, email null, dev-vs-prod failures, installation scope, org OAuth restrictions, bad_verification_code, rate limits, permission re-authorization, and migration issues.

Requires serverpod_auth_idp_server 3.5.0-beta.8 or later for configureFlutterWebAuth2CallbackRoute. Depends on serverpod/serverpod#5133.

@Zfinix Zfinix self-assigned this May 18, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant