GitHub OAuth Setup

This guide covers how to enable “Continue with GitHub” login for your ZShip project.

Prerequisites

Before you begin, make sure:

• Your ZShip system is deployed and running
• You have access to the admin panel
• You have a GitHub account with permission to create OAuth Apps

1. Create a GitHub OAuth App

Go to GitHub and create a new OAuth App.

For a personal account

1. Go to GitHub Developer Settings → OAuth Apps
2. Click New OAuth App

For an organization

1. Go to https://github.com/organizations/{your-org}/settings/applications
2. Click New OAuth App

Fill in the required fields

Field	Value
Application name	Your app name (e.g. ZShip)
Homepage URL	Your app URL (e.g. https://app.zship.ai)
Authorization callback URL	https://{your-domain}/api/auth/github-callback

Replace {your-domain} with your actual domain. For example:

• ZShip app: https://app.zship.ai/api/auth/github-callback
• Landing/web: https://zship.ai/api/auth/github-callback

Get your credentials

After creating the OAuth App:

1. Copy the Client ID — you will need it in the next step
2. Click Generate a new client secret
3. Copy the Client Secret immediately — GitHub will only show it once

2. Configure in Admin Panel

1. Log in to the admin panel
2. Go to Projects and select (or edit) your project
3. Expand the OAuth Providers section
4. Find the GitHub card:
   • Toggle the switch to Enabled
   • Paste the Client ID from step 1
   • Paste the Client Secret from step 1
5. Click Save

Once saved, the “Continue with GitHub” button will automatically appear on the login page.

3. Verify the integration

1. Open your app’s login page
2. You should see a Continue with GitHub button below the Google sign-in button (if configured)
3. Click it — you should be redirected to GitHub’s authorization page
4. After authorizing, you should be redirected back and logged in

How it works

The GitHub OAuth flow uses the standard Authorization Code grant:

1. User clicks “Continue with GitHub” on the login page
2. Browser redirects to GitHub’s authorization page with user:email scope
3. User authorizes the app on GitHub
4. GitHub redirects back to /api/auth/github-callback with an authorization code
5. The server exchanges the code for an access token (using the client secret)
6. The server fetches the user’s GitHub profile and verified email
7. The user is logged in (or auto-registered) and redirected to the dashboard

Multiple callback URLs

If you run both apps/zship and apps/web, each needs its own callback URL.

GitHub OAuth Apps only support one callback URL. You have two options:

Option A: Create two OAuth Apps

Create separate OAuth Apps for each frontend, each with its own callback URL:

• https://app.zship.ai/api/auth/github-callback (for zship)
• https://zship.ai/api/auth/github-callback (for web)

Then configure each project in admin with the corresponding client ID and secret.

Option B: Use one OAuth App with a shared domain

If both apps share the same domain (e.g. via path-based routing), you only need one OAuth App.

Troubleshooting

”GitHub sign-in is not configured”

The GitHub provider is not enabled or the client ID is missing in the admin panel. Go to Admin → Projects → OAuth Providers and check the GitHub configuration.

”Unable to retrieve email from GitHub”

The GitHub account does not have a verified email, or the email is set to private without the user:email scope. Make sure the OAuth App requests the user:email scope (this is handled automatically by ZShip).

Redirect URI mismatch

The callback URL configured in GitHub must exactly match https://{your-domain}/api/auth/github-callback. Check for trailing slashes, protocol (must be https), and domain mismatches.