GitHub OAuth - Automagik Suite Documentation

Overview

Forge integrates deeply with GitHub for repository management, authentication, and collaboration. GitHub OAuth enables secure, seamless access to your repositories.

Good News: Forge includes default OAuth credentials for development. Custom configuration is optional!

Quick Start (Default Credentials)

For most users, no configuration is needed:

Launch Forge

forge start
# Opens http://localhost:3000

Click GitHub Sign In

The UI will show “Sign in with GitHub”

Authorize Namastex Labs

GitHub will ask to authorize the default Forge OAuth app

Start Building

You’re authenticated and ready to create tasks!

The default credentials are perfect for local development and testing. No setup required!

Custom GitHub OAuth App

Want to use your own OAuth app? Here’s how to set it up.

Why Use Custom OAuth?

Production deployments on custom domains
Enterprise environments with specific security requirements
Team collaboration with your organization’s branding
Higher rate limits specific to your app

Creating Your OAuth App

Go to GitHub Settings

Navigate to GitHub Developer Settings→ OAuth Apps → New OAuth App

Fill in Application Details

Application name: My Forge Instance
Homepage URL: http://localhost:3000
Authorization callback URL: http://localhost:3000/auth/github/callback

The callback URL must match exactly! Include protocol (http:// or https://)

Click “Register application”

Generate Client Secret

After creation, click “Generate a new client secret”

Copy the secret immediately! GitHub only shows it once.

Save Credentials

You’ll have:

Client ID: Iv1.1234567890abcdef
Client Secret: 1234567890abcdef1234567890abcdef12345678

Configuration

Environment Variables

Set your custom credentials via environment variables:

export GITHUB_CLIENT_ID=Iv1.1234567890abcdef
export GITHUB_CLIENT_SECRET=1234567890abcdef1234567890abcdef12345678

Or in a .env file:

.env

GITHUB_CLIENT_ID=Iv1.1234567890abcdef
GITHUB_CLIENT_SECRET=1234567890abcdef1234567890abcdef12345678

Start Forge

forge start

# You should see:
# ✓ GitHub OAuth: Using custom credentials
# ✓ Backend running on http://127.0.0.1:8080
# ✓ Frontend running on http://localhost:3000

Multiple Environments

Development

.env.development

# Use default Forge credentials (no config needed)
# OR set custom:
GITHUB_CLIENT_ID=Iv1.dev_client_id
GITHUB_CLIENT_SECRET=dev_secret

OAuth App Settings:

Homepage URL: http://localhost:3000
Callback URL: http://localhost:3000/auth/github/callback

Staging

.env.staging

GITHUB_CLIENT_ID=Iv1.staging_client_id
GITHUB_CLIENT_SECRET=${STAGING_GITHUB_SECRET}

OAuth App Settings:

Homepage URL: https://forge-staging.yourdomain.com
Callback URL: https://forge-staging.yourdomain.com/auth/github/callback

Production

.env.production

GITHUB_CLIENT_ID=${GITHUB_CLIENT_ID}
GITHUB_CLIENT_SECRET=${GITHUB_CLIENT_SECRET}

OAuth App Settings:

Homepage URL: https://forge.yourdomain.com
Callback URL: https://forge.yourdomain.com/auth/github/callback

Never hardcode production secrets! Use secret management:

AWS Secrets Manager
HashiCorp Vault
Kubernetes Secrets
Azure Key Vault
Google Secret Manager

Permissions & Scopes

Required Scopes

Forge requests these GitHub OAuth scopes:

Scope	Purpose	Required
`repo`	Read/write repository access	✅ Yes
`user:email`	Access user email	✅ Yes
`read:user`	Read user profile	✅ Yes
`workflow`	Manage GitHub Actions	⚠️ Optional

Why Each Scope?

repo - Repository Access

What it does: Full control of private repositoriesWhy needed:

Clone repositories for tasks
Create and manage git worktrees
Commit changes from AI agents
Push branches and create PRs

This is the core permission Forge needs to function

user:email - Email Access

What it does: Access user email addressesWhy needed:

Associate commits with correct author
Send notifications (if enabled)
User identification in audit logs

read:user - Profile Access

What it does: Read user profile informationWhy needed:

Display username and avatar in UI
Team collaboration features
Activity tracking

workflow - GitHub Actions (Optional)

What it does: Access GitHub Actions workflowsWhy needed:

Trigger CI/CD on task completion
Monitor workflow status
Auto-deployment features

Only needed if you use GitHub Actions integration

Testing Your OAuth Setup

Verify Configuration

# Start Forge with your credentials
GITHUB_CLIENT_ID=your_id GITHUB_CLIENT_SECRET=your_secret forge start

# Check logs for:
✓ GitHub OAuth: Using custom credentials
✓ Client ID: Iv1.xxx...

Test Authentication Flow

Open Forge UI

Navigate to http://localhost:3000

Click GitHub Sign In

Should redirect to GitHub authorization page

Verify OAuth App Name

Should show YOUR app name (not “Forge by Namastex Labs”)

Authorize Access

Click “Authorize” and you should be redirected back

Check User Info

You should see your GitHub avatar and username in Forge UI

Troubleshooting

Callback URL mismatch

Error: “The redirect_uri MUST match the registered callback URL for this application”Solution:

Check your OAuth app settings on GitHub
Ensure callback URL exactly matches (including protocol and port)
For local dev: http://localhost:3000/auth/github/callback
Update OAuth app if needed

Invalid client

Error: “Invalid OAuth client_id”Solution:

Verify GITHUB_CLIENT_ID is correct
Check for extra spaces or quotes
Ensure OAuth app isn’t deleted
Try regenerating client secret

Authorization failed

Error: Authentication completes but user not logged inSolution:

Check GITHUB_CLIENT_SECRET is correct
Ensure secret hasn’t been rotated
Verify environment variables are loaded
Check backend logs for detailed errors

Rate limit errors

Error: “API rate limit exceeded”Solution:

Create authenticated OAuth app (higher limits)
Use personal access token for development
Implement caching for repository data
Contact GitHub for higher limits

Localhost not working

Error: OAuth redirect fails in browserSolution: Use 127.0.0.1 instead of localhost:

Callback URL: http://127.0.0.1:3000/auth/github/callback

Some browsers treat these differently!

Security Best Practices

Rotate Secrets Regularly

Generate new client secrets every 90 days

# GitHub Settings → OAuth Apps
# → Your App → Generate new client secret

Use Minimal Scopes

Only request permissions you actually needRemove workflow scope if not using Actions

Monitor Access Logs

Review GitHub OAuth authorizations periodicallygithub.com/settings/applications

Secure Production Secrets

Never commit secrets to version control

.gitignore

.env
.env.production
.env.local

Advanced: Organization OAuth Apps

For team deployments, use GitHub Organization OAuth apps:

Go to Organization Settings

https://github.com/organizations/YOUR_ORG/settings/applications

Create OAuth App

Same process as personal OAuth app

Set Organization Restrictions

Configure which repositories Forge can access

Add to Forge

Use organization OAuth credentials in Forge config

Organization Benefits

Centralized management: Admins control OAuth apps
Fine-grained permissions: Restrict repository access
Audit logs: Track all OAuth usage
Team collaboration: Share Forge instance across team

Production Deployment Checklist

Create Production OAuth App

Use your production domain
Set HTTPS callback URL
Document client ID/secret securely

Store Secrets Securely

# AWS Secrets Manager
aws secretsmanager create-secret \
  --name forge/github/client-secret \
  --secret-string "your_secret"

# Kubernetes
kubectl create secret generic forge-github \
  --from-literal=client-id=your_id \
  --from-literal=client-secret=your_secret

Configure Environment

GITHUB_CLIENT_ID=$(get-secret forge/github/client-id)
GITHUB_CLIENT_SECRET=$(get-secret forge/github/client-secret)

Test Production Flow

Test OAuth from production domain
Verify callback redirects correctly
Check user can access repositories

Monitor & Rotate

Set calendar reminder for 90-day rotation
Monitor OAuth access logs
Track API rate limits

Rate Limits

GitHub API Limits

Authentication	Requests/Hour	Notes
Unauthenticated	60	Very limited
OAuth App	5,000	Standard limit
GitHub App	15,000+	Higher limit
Enterprise	Custom	Contact GitHub

Optimizing Rate Limit Usage

Caching
Batch Requests
Webhooks

// Cache repository data locally
const cache = new Map();

async function getRepo(owner, repo) {
  const key = `${owner}/${repo}`;
  if (cache.has(key)) return cache.get(key);

  const data = await github.getRepo(owner, repo);
  cache.set(key, data);
  return data;
}

// Batch multiple operations
const repos = await github.listRepos({ per_page: 100 });

// Instead of:
// for (const repo of repos) {
//   await github.getRepo(repo.name);
// }

Use webhooks instead of polling:

# Receive events instead of checking
webhook_url: https://forge.yourdomain.com/webhooks/github
events:
  - push
  - pull_request
  - issues

Next Steps

Environment Variables

Complete configuration reference

LLM Configuration

Set up AI coding agents

Quick Start

Create your first task

Project Structure

Understand Forge’s organization

​Overview

​Quick Start (Default Credentials)

​Custom GitHub OAuth App

​Why Use Custom OAuth?

​Creating Your OAuth App

​Configuration

​Environment Variables

​Start Forge

​Multiple Environments

​Development

​Staging

​Production

​Permissions & Scopes

​Required Scopes

​Why Each Scope?

​Testing Your OAuth Setup

​Verify Configuration

​Test Authentication Flow

​Troubleshooting

​Security Best Practices

Rotate Secrets Regularly

Use Minimal Scopes

Monitor Access Logs

Secure Production Secrets

​Advanced: Organization OAuth Apps

​Organization Benefits

​Production Deployment Checklist

​Rate Limits

​GitHub API Limits

​Optimizing Rate Limit Usage

​Next Steps

Environment Variables

LLM Configuration

Quick Start

Project Structure

Overview

Quick Start (Default Credentials)

Custom GitHub OAuth App

Why Use Custom OAuth?

Creating Your OAuth App

Configuration

Environment Variables

Start Forge

Multiple Environments

Development

Staging

Production

Permissions & Scopes

Required Scopes

Why Each Scope?

Testing Your OAuth Setup

Verify Configuration

Test Authentication Flow

Troubleshooting

Security Best Practices

Advanced: Organization OAuth Apps

Organization Benefits

Production Deployment Checklist

Rate Limits

GitHub API Limits

Optimizing Rate Limit Usage

Next Steps