docs: Enhance GitHub Sign-In setup, customizations, and troubleshooting#521
Open
Zfinix wants to merge 7 commits into
Open
docs: Enhance GitHub Sign-In setup, customizations, and troubleshooting#521Zfinix wants to merge 7 commits into
Zfinix wants to merge 7 commits into
Conversation
…ckRoute and enhance troubleshooting steps
Swiftaxe
reviewed
May 29, 2026
…etup.md Co-authored-by: Alexander Dahlberg <dustbin4ever@gmail.com>
… refining language and punctuation
Swiftaxe
reviewed
Jun 3, 2026
| Serverpod can host this callback for you when the Flutter web app is served by the same Serverpod server (the default project template, which copies the Flutter web build into Serverpod's `web/app/` directory via the `flutter_build` script). Use the static `auth.html` fallback only if your Flutter web app is hosted on a different origin (for example, a separate dev server during local development, or a CDN in production). | ||
| ```bash | ||
| flutter build web --output ../my_project_server/web/app # from your Flutter project | ||
| dart run bin/main.dart # from your server project |
Collaborator
There was a problem hiding this comment.
Is this the recommended workflow for this even though we have the new serverpod start workflow?
Swiftaxe
reviewed
Jun 3, 2026
| 2. Add the full callback URL to your GitHub App's **Callback URL** field (e.g., `http://localhost:8082/auth/callback` locally, `https://my-awesome-project.serverpod.space/auth/callback` in production). GitHub Apps accept up to 10 entries, so dev and prod entries can coexist. | ||
|
|
||
| 2. Register `https://my-awesome-project.serverpod.space/auth/callback` as a **Callback URL** on your GitHub App. | ||
| 3. Pass the same URL to `initializeGitHubSignIn` via the `redirectUri` argument when you initialize the client (covered in [Initialize the GitHub sign-in service](#initialize-the-github-sign-in-service) below). |
Collaborator
There was a problem hiding this comment.
Having a step here mentioning something below gets confusing. Instead, refer back to the callback URL in step 2, from the section below, and remove this step 3. It adds noise and confusion.
Swiftaxe
reviewed
Jun 3, 2026
|
|
||
| :::note | ||
| `FlutterWebAuth2CallbackRoute` requires `serverpod_auth_idp_server` 3.5.0-beta.8 or later. On earlier versions, use the [Separately-hosted Flutter web](#separately-hosted-flutter-web-or-local-flutter-dev-server) flow instead. | ||
| `FlutterWebAuth2CallbackRoute` requires `serverpod_auth_idp_server` 3.5.0-beta.8 or later. |
Collaborator
There was a problem hiding this comment.
Requirements shall be put at the top before starting, just as in the other guides.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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
FlutterWebAuth2CallbackRouteand relied on a manually-createdauth.htmleven when Serverpod could serve the callback itself.Solution
## Publishing to productionsection with self-hosted and Serverpod Cloud (scloud password set) paths. Web flow refactored into Serverpod-hosted (usingpod.configureFlutterWebAuth2CallbackRoute()and/auth/callback) and separately-hosted (staticauth.html) sub-paths. Five new screenshots replace the stale set.02-configuration.mdto02-customizations.mdfor parity with Google. AddedGitHubIdpConfigvsGitHubIdpConfigFromPasswordsintro, manual credential loading, server-side API access viagetExtraGitHubInfoCallback, globalonBeforeAuthUserCreated/onAfterAuthUserCreatedhooks, and a parameter reference table.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_server3.5.0-beta.8 or later forconfigureFlutterWebAuth2CallbackRoute. Depends on serverpod/serverpod#5133.