docs(oauth): surface and document GitLab login support

[appleboy]

Summary

GitLab OAuth login has been fully implemented and tested in the codebase since PR #70 (provider in internal/auth/oauth_gitlab.go, config fields, bootstrap registration, login button + tests), but the documentation and .env.example never caught up — so operators could not discover or configure it, and some text actively described GitLab as a future addition. This PR closes that documentation/config gap. No code, templates, or tests change.

• Add a GitLab section to .env.example and the configuration guide (GITLAB_OAUTH_ENABLED, GITLAB_URL, GITLAB_CLIENT_ID, GITLAB_CLIENT_SECRET, GITLAB_REDIRECT_URL, GITLAB_SCOPES)
• Add a dedicated GitLab OAuth Setup section and env-var reference rows to docs/OAUTH_SETUP.md
• List GitLab as a supported provider across README.md, CLAUDE.md, and the docs; fix the stale "Easy to add GitLab" line
• Rewrite the "adding a provider" tutorial off the now-built-in GitLab onto a Google example aligned with the current architecture
• Follow-up corrections from review: complete GitLab provider lists in docs/ARCHITECTURE.md, docs/METRICS.md, docs/USE_CASES.md; fix the OAuth route paths in CLAUDE.md; correct the GitLab application UI path; clarify read_user returns the primary email; scope auth_login_total's auth_source label to local/http_api; correct the post-login redirect target; and clarify that same-email account linking requires a provider-verified email (GitLab/Gitea are unverified)

AI Authorship

• AI was used. Details:
  • Tool / model: Claude Opus 4.7 (1M context) via Claude Code, plan-mode workflow (plan saved at ~/.claude/plans/support-gitlab-login-ancient-balloon.md)
  • AI-authored files: all 8 in the diff — .env.example, CLAUDE.md, README.md, docs/ARCHITECTURE.md, docs/CONFIGURATION.md, docs/METRICS.md, docs/OAUTH_SETUP.md, docs/USE_CASES.md
  • Human line-by-line reviewed: all 8 files reviewed line-by-line by the author before merge

Change classification

• Leaf node — documentation/config only. No executable code, no behavior change. Failure mode is "docs are wrong/incomplete"; no system-wide impact.

Plan reference

Goal: make the already-working GitLab provider a first-class, discoverable, documented option. Operators can find GITLAB_* settings in .env.example, follow a real GitLab setup section in the docs, and provider lists no longer omit GitLab or describe it as hypothetical. No functional changes. (Plan: ~/.claude/plans/support-gitlab-login-ancient-balloon.md.)

Verification

• All values sourced from the existing implementation: default GITLAB_URL=https://gitlab.com and default scope read_user match internal/config/config.go and auth.NewGitLabProvider.
• go test ./internal/auth/... → ok (no code touched; GitLab provider tests still pass).
• Consistency sweep: grep confirms every provider list naming GitHub/Gitea/Microsoft now also names GitLab, and no remaining text claims GitLab is unsupported / "to be added".
• Doc claims cross-checked against code: route paths (internal/bootstrap/router.go), metric labels (RecordLogin / RecordOAuthCallback call sites), redirect target (oauth_handler.go), and email-verified linking gate (internal/services/user.go).
• Note: go build ./... fails only on the generated api (Swagger) package, which requires make generate in a fresh worktree — pre-existing and unrelated to this diff.

Reviewer manual check: render the docs diff in GitHub preview; confirm the new "GitLab OAuth Setup" section reads consistently with the GitHub/Gitea sections, and that the rewritten "Adding More OAuth Providers" example no longer references built-in GitLab.

Risk & rollback

• Risk: None functional. Doc/config-only. Worst case: wording or an example is unclear.
• Rollback: git revert — content-only commits.

Reviewer guide

• Read carefully: the new ## GitLab OAuth Setup section and the rewritten ## Adding More OAuth Providers section in docs/OAUTH_SETUP.md, plus the email-linking and metrics-label clarifications — these are the substantive prose to sanity-check against the implementation (internal/auth/oauth_gitlab.go, internal/bootstrap/oauth.go, internal/services/user.go).
• Spot-check OK: the one-line provider-list additions in README.md, CLAUDE.md, docs/ARCHITECTURE.md, docs/METRICS.md, docs/USE_CASES.md, docs/CONFIGURATION.md, and the .env.example block (mirrors the existing Gitea block).

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[Copilot]

Pull request overview

Surfaces already-implemented GitLab OAuth login support by updating operator-facing documentation and example configuration, and removes stale language implying GitLab is a future addition.

Changes:

• Add GITLAB_* environment variables to .env.example and the configuration docs.
• Extend provider lists across docs to include GitLab and update OAuth-related prose/tutorials accordingly.
• Add a GitLab-specific setup section and env-var reference rows to docs/OAUTH_SETUP.md.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
README.md	Updates provider lists and the OAuth setup guide link description to include GitLab.
docs/OAUTH_SETUP.md	Adds GitLab setup steps, GitLab env-var reference rows, and rewrites the “adding a provider” tutorial.
docs/CONFIGURATION.md	Documents GitLab OAuth env vars and updates supported-provider text.
CLAUDE.md	Updates internal docs/provider lists to include GitLab.
.env.example	Adds a GitLab OAuth configuration block for discoverability.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 8 out of 8 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

Copilot reviewed 8 out of 8 changed files in this pull request and generated 3 comments.

[Copilot]

Pull request overview

Copilot reviewed 8 out of 8 changed files in this pull request and generated 2 comments.

Comments suppressed due to low confidence (1)

docs/OAUTH_SETUP.md:230

• This example implies GitHub+Gitea+GitLab can all be linked to the same AuthGate account. In the current implementation, GitLab and Gitea always report EmailVerified=false and therefore cannot be auto-linked by email; if an account already owns that email, an unverified provider login (with no existing OAuthConnection) fails due to the UNIQUE email constraint. Consider revising the example to avoid showing multiple unverified providers linked to the same account, or explicitly describe the ordering/limitation (e.g., start with one unverified provider account, then link verified providers).

  - Local auth: alice / password123
  - GitHub: alice-github (linked)
  - Gitea: alice-work (linked)
  - GitLab: alice-gitlab (linked)

All methods log into the same AuthGate account.

[Copilot]

Pull request overview

Copilot reviewed 8 out of 8 changed files in this pull request and generated no new comments.