3. Register the GitHub OAuth app

Before your Python code can send a user to GitHub, GitHub needs an application record to trust. That record gives you a Client ID, a Client Secret, and a callback URL. Your local project then stores those values in .env so the examples can use them without hardcoding secrets.

OAuth Apps and GitHub Apps

GitHub has two app models that can both participate in OAuth-style authorization. GitHub Apps are the production-preferred model for many integrations because they support fine-grained repository permissions and short-lived tokens. OAuth Apps are simpler and expose the classic OAuth flow directly: client ID, client secret, authorization URL, callback, token exchange.

This chapter uses a GitHub OAuth App because the goal is to understand OAuth itself. You will see the moving parts directly instead of hiding them behind a library or app framework. In production, especially for a public GitHub integration, you should compare OAuth Apps with GitHub Apps before choosing the model.

Create the local project

Start with a clean folder for the chapter code:

mkdir dev-github-tool
cd dev-github-tool
python -m venv .venv

Activate the virtual environment for your shell:

.\.venv\Scripts\Activate.ps1

source .venv/bin/activate

Save the chapter dependencies as requirements.txt:

requests
python-dotenv

Install them:

python -m pip install -r requirements.txt

The examples use requests for HTTP calls and python-dotenv so local scripts can load configuration from a .env file.

Register the OAuth App in GitHub

Now create the application record in GitHub:

The homepage URL identifies the app while you are developing locally. The callback URL is more important: it must match the URL your Python script will listen on later.

1. Open GitHub in your browser.
2. Go to Settings, then Developer settings.
3. Choose OAuth Apps.
4. Click New OAuth App. If you have never created one before, GitHub may label this button Register a new application.
5. Use Dev GitHub Tool as the application name.
6. Use http://localhost:8000 as the homepage URL.
7. Use http://localhost:8000/callback as the authorization callback URL.
8. Register the application.
9. Copy the Client ID.
10. Generate a new client secret and copy it immediately.

Understand the callback URL

The callback URL is where GitHub sends the browser after the user approves or cancels the OAuth request. In this chapter, your Python script will briefly listen on localhost:8000 and handle one request to /callback.

GitHub OAuth Apps have a single configured callback URL. Later, when your authorization URL includes a redirect_uri, keep it aligned with the callback URL you registered. If your code listens on http://localhost:8000/callback but your GitHub app is configured with a different host, port, or path, the flow will fail before your Python code receives a token.

Local OAuth callbacks are allowed for development, but they are not production deployment. A real hosted web application should use an HTTPS callback URL on its own domain.

Store credentials in .env

Create a file named .env in the project root:

GITHUB_CLIENT_ID=replace_with_your_client_id
GITHUB_CLIENT_SECRET=replace_with_your_client_secret
GITHUB_REDIRECT_URI=http://localhost:8000/callback

Then create .gitignore so Git ignores both secrets and local environment files:

.env
.venv/
__pycache__/

Verify that Python can load the values:

import os
from dotenv import load_dotenv

load_dotenv()

CLIENT_ID = os.getenv("GITHUB_CLIENT_ID")
CLIENT_SECRET = os.getenv("GITHUB_CLIENT_SECRET")
REDIRECT_URI = os.getenv("GITHUB_REDIRECT_URI")

if not CLIENT_ID or not CLIENT_SECRET or not REDIRECT_URI:
    raise SystemExit("Missing one or more GitHub OAuth settings in .env")

print(f"Client ID loaded: {CLIENT_ID[:6]}...")
print("Client secret loaded: [hidden]")
print(f"Redirect URI: {REDIRECT_URI}")

Run the check:

python check_config.py

If the script prints the masked Client ID and the redirect URI, your setup is ready. The next step is to build the authorization URL that sends the user to GitHub with the right permissions and the right security parameters.