Configure GitHub OAuth

Saavo already implements GitHub sign-in. Register an OAuth App with GitHub and configure its callback URL and two credentials. You do not need to write authorization, callback, or user profile retrieval code.

Once configured, the sign-in and sign-up pages automatically show a GitHub option. During authorization, the template requests read:user and user:email to read the user's GitHub profile and email addresses. It does not request repository permissions.

Choose URLs before you begin

After authorization, GitHub needs to return the user to Saavo's GitHub callback endpoint. The default path is in config/deploy.ts:

ui: {
    oauthRedirectTo: {
        github: '/api/auth/oauth2/github',
        google: '/api/auth/oauth2/google',
    },
},

The callback URL combines the site origin and callback path. For this example project:

Run npm run dev first and use the address actually shown in the terminal. If the port is not 5173, update the callback URL's port as well. In production, use VITE_SITE_URL from .env.production.

Create a GitHub OAuth App

See GitHub's Creating an OAuth app for current UI and field descriptions, and Authorizing OAuth apps for callback matching rules.

Configure the local environment

Open .env in the project root and enter the two values you obtained:

GITHUB_CLIENT_ID="Your GitHub Client ID"
GITHUB_CLIENT_SECRET="Your GitHub Client Secret"

Save and restart the development server:

npm run doctor
npm run dev

When doctor no longer shows GitHub OAuth is not configured, both variables have been read. If you fill in only one, doctor reports the missing value and GitHub sign-in remains disabled on the sign-in page.

Configure production

After the initial deployment, open .env.production and enter the credentials for production:

GITHUB_CLIENT_ID="Your production GitHub Client ID"
GITHUB_CLIENT_SECRET="Your production GitHub Client Secret"

Then run:

npm run doctor:remote
npm run deploy:update

The deployment script synchronizes the Client ID to Cloudflare as a Worker variable and the Client Secret as an encrypted secret. Do not enter them only through the Cloudflare Dashboard. The local record and remote environment may otherwise differ the next time you run deploy:update.

If the project has not completed its initial deployment, you can leave the OAuth variables empty and run npm run deploy:init. Once you have the actual workers.dev address, add its full callback URL to the GitHub OAuth App, fill in .env.production, and run npm run deploy:update.

After binding webpagetopdf.dev, also add this URL to the OAuth App:

https://webpagetopdf.dev/api/auth/oauth2/github

Changing only VITE_SITE_URL without updating GitHub causes a callback URL mismatch when users return from authorization.

Verify GitHub sign-in

Do more than check for the button. Complete this flow with a real GitHub account:

1. Open the site's sign-in page and confirm that the GitHub option appears.
2. Click it and confirm that the browser opens github.com and shows the OAuth App you just created.
3. Review the requested permissions. Repository read or write permissions should not appear.
4. Approve access and confirm that the browser returns to Saavo with the user signed in.
5. Sign out, then sign in again with the same GitHub account and confirm that no duplicate user is created.
6. Test with an account whose GitHub email is private and confirm that the template still reads an available email address through user:email.

Test local and production-domain sign-in separately. Correct production settings do not prove that the callback URL for the local port is correct.

Common issues