Skip to main content
GitHub OAuth setup offers two approaches: GitHub App with automated setup, or traditional OAuth App with manual configuration.

​
Setup Options

When you run oauth-init and select GitHub, you’ll choose between:
  • GitHub App (One click setup) - Automated setup using GitHub’s app manifest flow
  • OAuth App (Manual setup) - Traditional OAuth app requiring form completion
The GitHub App flow uses GitHub’s app manifest API for automated credential generation.
1

Choose GitHub App

Select “GitHub App (One click setup)” from the menu.
2

Choose Save Option

Select where to save credentials before the app is created:
  • .env - Save to .env file
  • .env.local - Save to .env.local file
  • .json - Save to JSON file
  • print to the console - Display in terminal
3

Authorize in Browser

OAuth Init starts a local server on port 3004 and opens your browser to GitHub.A form is automatically submitted with this manifest:
{
  "name": "oauth-init-app",
  "url": "http://localhost:3000",
  "callback_url": "YOUR_CALLBACK_URL",
  "public": false,
  "default_permissions": {
    "contents": "read",
    "metadata": "read"
  },
  "redirect_url": "http://localhost:3004/callback"
}
GitHub will prompt you to authorize the app creation.
4

Automatic Credential Exchange

After authorization, GitHub redirects to the local server with a code.OAuth Init exchanges this code for your Client ID and Client Secret:
curl -X POST https://api.github.com/app-manifests/{code}/conversions
The credentials are automatically saved according to your chosen option.

​
How It Works

The GitHub App flow:
  1. Creates a local HTTP server on http://localhost:3004
  2. Opens browser to /callback which auto-submits a form to GitHub
  3. GitHub creates the app and redirects back with a temporary code
  4. The code is exchanged for permanent credentials via GitHub’s API
  5. Credentials are saved and the server shuts down

​
OAuth App (Manual)

The OAuth App flow requires manual form completion in GitHub’s developer settings.
1

Choose OAuth App

Select “OAuth App (You need to fill a form for this)” from the menu.
2

Create OAuth App

OAuth Init opens the GitHub OAuth app registration page:
https://github.com/settings/applications/new
Complete the form:
  1. Application name - Choose any name for your app
  2. Homepage URL - Your application’s homepage (e.g., http://localhost:3000)
  3. Authorization callback URL - The callback URL provided by OAuth Init
  4. Click Register application
Press Enter in the CLI once you’ve created the OAuth App.
3

Get Client Credentials

After creating the app, you’ll see your Client ID immediately.To get the Client Secret:
  1. Click Generate a new client secret
  2. Copy the secret (it will only be shown once)
4

Enter Credentials

Paste your credentials when prompted:Client ID:
Iv1.1234567890abcdef
Client Secret:
1234567890abcdef1234567890abcdef12345678
5

Save Credentials

Choose where to save your credentials:
  • .env - Save to .env file in your project root
  • .env.local - Save to .env.local file (ideal for Next.js projects)
  • .json - Save to github-credentials.json file
  • print to the console - Display credentials in terminal without saving
See Save Options for detailed information about each format.

​
Validation

Unlike other providers, GitHub OAuth App setup does not enforce strict validation on the Client ID format. However, GitHub Client IDs typically:
  • OAuth Apps: Start with Iv1. followed by 16 hexadecimal characters
  • GitHub Apps: Use numeric Client IDs

​
CLI Options

When running OAuth Init, you can use various flags to customize behavior: 
# Standard interactive setup
oauth-init

# Skip browser opening (get URLs in console)
oauth-init --no-open

# Quiet mode (minimal output)
oauth-init --quiet

# Combine flags
oauth-init --quiet --no-open
See CLI Options for all available flags.

​
Comparison

FeatureGitHub AppOAuth App
Setup SpeedFast (one-click)Slower (manual form)
AutomationFully automatedManual credential copy
PermissionsPreset (contents, metadata)Configured in GitHub
Local ServerRequired (port 3004)Not required
Best ForQuick setup, developmentProduction, custom permissions

Build docs developers (and LLMs) love

Get started for freeTalk to us