Add GitHub Auth - GitHub OAuth Configuration

Communication

• Detect the user's language from the conversation (the user's own messages, anywhere in the session - not just this invocation: a bare slash command like /bootstrap carries no language signal by itself). If nothing in the conversation gives a signal, fall back to the OS locale (node -e "console.log(Intl.DateTimeFormat().resolvedOptions().locale)") before defaulting to English. ALWAYS reply in that language for every user-facing message: questions, progress, confirmations, summaries, errors - including any example text quoted in this skill, which is illustrative and must be translated, never sent verbatim.
• Use plain, non-technical business language. Never expose internal script names (*.mjs) or jargon; describe actions in human terms.
• When generating user-facing content for the scaffolded project (UI labels, emails, copy), write it in the user's language too.
• Show progress as a short natural-language checklist (in-progress and done states).

Adds GitHub OAuth authentication to an existing project. Can be used:

• Standalone (/add-github-auth) - on a project that already has NextAuth configured (via /add-auth or /bootstrap)
• From /add-auth - when the user picks GitHub as a provider

This skill walks the user step by step through the GitHub settings, then Claude Code takes over to configure the environment variables everywhere.

Prerequisites

Before starting, identify:

• The project's local URL: http://localhost:3000
• The production URL (from Vercel or CLAUDE.md)
• The NextAuth callback URL: <base_url>/api/auth/callback/github

Step 0 - Preflight: is NextAuth installed?

This skill requires NextAuth to already be in place (via /add-auth or /bootstrap). We check before sending the user into the GitHub configuration for nothing.

Invoke _check-deps auth:

result=$(node "${CLAUDE_SKILL_DIR}/../../scripts/check-deps.mjs" auth)
auth_ok=$(echo "$result" | node -e "console.log(JSON.parse(require('fs').readFileSync(0,'utf8')).auth.ok)")
auth_mode=$(echo "$result" | node -e "console.log(JSON.parse(require('fs').readFileSync(0,'utf8')).auth.mode || 'unknown')")

If auth_ok = false (no auth.ts or no AUTH_SECRET) - abort with a simple message:

⚠️ Basic authentication is not in place yet in this project. First run /add-auth to set up email/password login, then come back to /add-github-auth to add GitHub login on top of it.

If auth_mode = "admin-credentials" - abort. GitHub OAuth does not apply to admin mode (where you are the only one logging in with a fixed password). Message to the user:

Your project is configured in admin-only mode - only you log in via a fixed password. GitHub login is meant for a system where your users create accounts. So it is not compatible with your current setup.

If you would rather switch to a user-accounts system (with GitHub as a bonus), you need to start over from /add-auth, this time choosing "system for your users".

Otherwise (auth_mode = "user-credentials") → continue to Step 1.

Step 1 - Create an OAuth App on GitHub

Show this message to the user:

GitHub OAuth Configuration

We are going to set up GitHub authentication together. I will guide you through the GitHub settings, and I will take care of configuring everything on the code and Vercel side afterwards.

1. Open the GitHub developer settings: Go to github.com/settings/developers

(You can also get there via: GitHub → your avatar in the top right → Settings → Developer settings at the very bottom of the left menu)

2. Create a new OAuth App:

• Click "OAuth Apps" in the left menu
• Click "New OAuth App" (or "Register a new application")

3. Fill in the form:

• Application name: the name of your app (e.g. My App)
• Homepage URL: https://<production_url>
• Application description: optional, a short description of your app
• Authorization callback URL: http://localhost:3000/api/auth/callback/github

⚠️ We use the local URL for now. We will add the production URL afterwards.

4. Click "Register application"

Let me know when it is done.

Replace <production_url> with the project's real URL before displaying.

Wait for the user's confirmation before continuing.

Step 2 - Get the Client ID and generate the Client Secret

Show this message:

Get the credentials

You should now be on your OAuth App's page.

5. Client ID:

• The Client ID is displayed directly on the page (a string of ~20 characters)

6. Generate the Client Secret:

• Click "Generate a new client secret"
• GitHub shows the secret only once - copy it immediately
• ⚠️ If you leave the page without copying it, you will have to generate a new one

Do not paste them here. A window opens on your screen: type the Client ID (shown as you type) and the Client Secret (hidden) there. They go straight into the project and Vercel, never into our conversation.

Then open the masked window (the _collect-secret pattern, destination B: a secret of THIS project). Replace <LANG> with the conversation's language code:

node "${CLAUDE_SKILL_DIR}/../../scripts/vault/launch.mjs" collect-env --lang <LANG> \
  --keys "AUTH_GITHUB_ID:text,AUTH_GITHUB_SECRET:secret" \
  --project-dir "<absolute project dir>"

It blocks until the user is done, and exits non-zero if they cancel or the write fails: read the exit code, never assume success. The client secret never passes through the conversation: if the user pastes it in chat anyway, do not reuse it, and tell them to generate a new one on the OAuth App's page (the pasted one is in the session's transcript).

Step 3 - Claude Code configures everything

Once the window has written both values:

3a. The env vars

The window has written AUTH_GITHUB_ID and AUTH_GITHUB_SECRET to the local .env AND to Vercel (production and preview), idempotently, through _push-env-vars. Nothing else to push.

3b. Configure the provider in NextAuth

In src/server/auth.ts, make sure the GitHub provider is configured:

import GitHubProvider from "next-auth/providers/github";

// In the providers config:
GitHubProvider({
  clientId: process.env.AUTH_GITHUB_ID!,
  clientSecret: process.env.AUTH_GITHUB_SECRET!,
}),

3c. Add the "Continue with GitHub" button on the signin/signup pages

Invoke _detect-project-root to get WEB_DIR, then run the helper that patches the auth pages:

node "${CLAUDE_SKILL_DIR}/../../scripts/setup-oauth-button.mjs" \
  --web-dir "$WEB_DIR" \
  --provider github

The script:

• Detects src/app/signin/page.tsx and src/app/signup/page.tsx (or their equivalents under [locale]/ if i18n is active), and inserts a "Continue with GitHub" button + an "or" separator below the email/password submit button
• Is idempotent: if signIn("github" is already present in the page, it touches nothing; if an OAuth block already exists (Google added before), it stacks GitHub into it without duplicating the separator
• Automatically detects whether the page uses useTranslations (i18n variant) or hardcoded FR strings (plain variant), and writes the appropriate snippet
• If i18n is active, adds the keys signin.orSeparator, signin.continueWithGithub, signup.orSeparator, signup.continueWithGithub to the messages/<locale>.json files

Without this step, the GitHub provider would technically be configured on the server side but no button would be visible - the user would have to go through /api/auth/signin (NextAuth's fallback page) to use it.

3d. Update CLAUDE.md

Invoke _update-claude-md with:

• conventions: - **OAuth GitHub** : callback URL = \https://<production_url>/api/auth/callback/github``

Step 4 - Add the production callback URL

Show this message:

Add the production URL

Last manual step! You need to add the production callback URL in your GitHub OAuth App.

7. Go back to your OAuth App's page: github.com/settings/developers → click on your app's name

8. Edit the Authorization callback URL:

• Replace the current URL (http://localhost:3000/api/auth/callback/github)
• With the production URL: https://<production_url>/api/auth/callback/github

9. Click "Update application"

💡 Tip: GitHub supports only one callback URL per OAuth App. For local dev to work too, two options:

• Option A (recommended): create a second OAuth App dedicated to local dev (callback = http://localhost:3000/api/auth/callback/github) and use its credentials in the local .env
• Option B: switch the URL in the GitHub settings depending on whether you are testing locally or in prod

Let me know if you want me to help you create a second OAuth App for local dev.

Replace <production_url> with the project's real URL before displaying.

RGPD - Privacy policy

Add GitHub to the project's RGPD subprocessor registry:

node "${CLAUDE_SKILL_DIR}/../../scripts/update-privacy-policy.mjs" --add github-oauth

The helper is idempotent. If the politique-de-confidentialite/page.tsx page exists, it updates automatically. Otherwise, only the registry is created - /rgpd-audit can generate the page later.

Step 5 - Verification

Confirm to the user that everything is configured:

• .env updated with AUTH_GITHUB_ID and AUTH_GITHUB_SECRET
• Variables pushed to Vercel (production + preview)
• GitHub provider configured in src/server/auth.ts
• CLAUDE.md updated

Remind them that:

• Locally, test with pnpm dev then go to /signin - the "Continue with GitHub" button should appear below the email/password form
• GitHub OAuth has no test mode - any GitHub user can log in immediately
• If the user wants to restrict access, they must handle that on the application side (whitelist, roles, etc.)