Back to Overview

GitHub Login Setup

Let users sign in with their GitHub account. A two-minute setup with no special API scopes required.

Luka Breitig — Technical Product Builder & AI Developer
Luka Breitig

Technical Product Builder & AI Developer

Before you begin

  • A GitHub account
  • A domain with HTTPS configured
  • Tymeslot installed and running at your domain

By the end of this guide, users will be able to sign in to Tymeslot with their GitHub account. GitHub is the simplest OAuth provider to configure — no consent screen review, no API library to enable, no admin permissions required.

1 Create a GitHub OAuth App

  1. Go to github.com/settings/developers (or navigate via your GitHub avatar → [Settings] → [Developer settings]).
  2. Click [OAuth Apps] in the left sidebar, then [New OAuth App].
  3. Fill in the form:
    • — Application name: "Tymeslot" — this is the name users see on the GitHub authorization screen.
    • — Homepage URL: https://yourdomain.com
    • — Authorization callback URL: https://yourdomain.com/auth/github/callback
  4. Click [Register application]. You land on the app's settings page.

Organization-owned apps

If you want the OAuth app to be owned by a GitHub organization rather than your personal account, create it from the organization's settings: [Your organization] → [Settings] → [Developer settings] → [OAuth Apps]. The setup steps are identical from there.

2 Generate a Client Secret

  1. On the app settings page, click [Generate a new client secret].
  2. GitHub displays the secret value once. Copy it immediately.

Copy the secret before leaving the page

Once you navigate away, GitHub no longer shows the full secret value. If you lose it, click [Delete] next to the secret and generate a new one — this does not affect your Client ID or app configuration.

3 Copy Your Client ID

Your Client ID is displayed at the top of the app settings page, above the client secrets section. Unlike the client secret, it is always visible and can be retrieved at any time by returning to this page.

4 Configure Environment Variables

Add the following to your Tymeslot environment configuration and restart the server. 

# Enable GitHub Login
ENABLE_GITHUB_AUTH=true

# OAuth credentials (from Steps 2 and 3)
GITHUB_CLIENT_ID=your-client-id
GITHUB_CLIENT_SECRET=your-client-secret

After restarting, a Sign in with GitHub button appears on the login and registration pages.

What Users Experience

When a user clicks Sign in with GitHub, GitHub asks them to authorize access to their public profile and email address. No repository, organization, or code access is requested.

Tymeslot creates or links a user account using the email address from the user's GitHub profile. If an account already exists with the same email, GitHub login is automatically connected to it — users can continue using either their password or GitHub to sign in.

Users with private email addresses

GitHub allows users to mark their email address as private. When they do, the standard GitHub API returns a null email. Tymeslot handles this automatically by making a secondary request to fetch the user's primary verified email — this does not require any additional OAuth scopes. If a user has no verified email address on their GitHub account at all, they will be asked to add one before they can sign in.

Common Errors

Login redirects back to the login page with an error

The most common cause is a mismatch between the Authorization callback URL registered in GitHub and the URL Tymeslot is using. The match must be exact: same scheme (https://), same domain, same path, and no trailing slash. Open your GitHub OAuth App settings and confirm the callback URL matches https://yourdomain.com/auth/github/callback exactly.

"Sign in with GitHub" button does not appear

Confirm that ENABLE_GITHUB_AUTH=true is set in your environment and that you have restarted Tymeslot after adding the variable. Environment variables are only read at startup.

Login fails for a specific user but works for others

This is almost always the private email scenario. Ask the user to check their GitHub email settings at github.com/settings/emails and confirm they have at least one verified email address on their account.

❓ Frequently Asked Questions

GitHub login redirects back to an error page — what's wrong?

The most likely cause is a mismatch between the Authorization callback URL registered in your GitHub OAuth App and the URL Tymeslot sends during the OAuth flow. The value in GitHub must be exactly https://yourdomain.com/auth/github/callback — same scheme, same domain, same path, no trailing slash. Open your app at github.com/settings/developers and verify the callback URL character-for-character.

Users can log in with GitHub but their email isn't showing up — why?

GitHub allows users to mark their email address as private, in which case the standard profile API returns a null email field. Tymeslot handles this automatically by making a secondary request to GitHub's /user/emails endpoint to retrieve the user's primary verified email. If a user has no verified email address on their GitHub account at all, they will be prompted to add one before they can sign in.

Can I restrict GitHub login to users from my organization?

No. GitHub OAuth Apps do not support organization-level restrictions — any GitHub user can authorize the app and sign in if GitHub login is enabled on your Tymeslot instance. If you need to restrict access to a specific set of users, use Tymeslot's invitation-only mode or disable open registration in your instance settings.

I created the OAuth App but I'm getting a 'client_id not found' error — why?

Double-check that the GITHUB_CLIENT_ID environment variable contains the Client ID shown at the top of your GitHub OAuth App settings page, not the numeric App ID. These are two different values. The Client ID is an alphanumeric string (e.g., Iv1.a1b2c3d4e5f6a7b8); the App ID is a plain integer and is not used for OAuth.

Do I need to publish or submit my GitHub OAuth App for review?

No. GitHub OAuth Apps do not require review or publishing to work. They are available to users immediately after creation, in both development and production. Unlike GitHub Apps, there is no approval process and no distinction between "testing" and "production" modes.

Verification Checklist

Confirm each of the following after restarting Tymeslot:
  • A Sign in with GitHub button appears on the login and registration pages.
  • Clicking it redirects to GitHub's authorization screen, which names the app "Tymeslot".
  • After authorizing, you are redirected back to Tymeslot and signed in.
  • Your GitHub avatar and display name appear in your Tymeslot account.
  • The GitHub OAuth App settings page at github.com/settings/developers shows a non-zero count next to Users.

🔗 Related Articles

Read Google OAuth App Setup

Google OAuth App Setup

Create a Google OAuth app to enable Google Login, Google Calendar sync, and Google Meet room creation.

Read Microsoft Azure App Setup

Microsoft Azure App Setup

Register a Microsoft Azure app to enable Microsoft Login, Outlook Calendar sync, and Teams room creation.

Read Generic SSO (OAuth / OIDC)

Generic SSO (OAuth / OIDC)

Connect any OAuth 2.0 / OpenID Connect identity provider for single sign-on. Supports Keycloak, Authentik, Lemonldap::NG, Okta, Azure AD, and more.