GitHub Stale Fork Manager

A focused tool for managing inactive forked repositories on GitHub. Identify, archive, and delete stale forks in bulk with a clean, no-framework interface.

Features

• 🍴 Stale Fork Detection - Automatically identifies forks inactive beyond a configurable threshold
• ⚙️ Configurable Threshold - Set staleness period from 30 to 730 days (default: 180)
• 🔍 Advanced Filtering - Filter by visibility (public/private/internal) and archived status
• ☑️ Bulk Operations - Select and archive/delete multiple repositories at once
• 🔐 Secure OAuth - GitHub OAuth with minimal required scopes (repo, delete_repo)
• 🍪 Session-based Auth - HttpOnly cookies with 24-hour expiry
• 📊 Visual Dashboard - See repository details, parent links, and staleness metrics
• 🚦 Rate Limit Handling - Graceful handling of GitHub API rate limits
• 📝 Comprehensive Logging - All API calls logged for auditing
• 🎨 No Framework UI - Pure HTML/CSS/JavaScript for minimal complexity
• 🔄 Real-time Data - Always fetches fresh data from GitHub (no caching)

Architecture

Built with simplicity and security as core principles:

• Backend: Node.js + Express with minimal dependencies
• Frontend: Vanilla JavaScript (no frameworks)
• Authentication: GitHub OAuth with express-session
• API Client: @octokit/rest for typed GitHub API interactions
• Session Storage: In-memory sessions for authentication tokens

All GitHub API interactions are isolated in github-api.js for clean separation of concerns.

Prerequisites

• Node.js 22+ or Docker
• GitHub account with repositories to manage
• Either: GitHub Personal Access Token (recommended for local use)
• Or: GitHub OAuth App credentials (for shared/production deployments)

Setup Instructions

Authentication Options

You can authenticate using either a Personal Access Token (PAT) or OAuth:

Option 1: Personal Access Token (Recommended for Local Use)

Why PAT?

• No OAuth app setup required
• Fine-grained permissions with short expiration
• Perfect for local development
• No client secrets needed

Create a Fine-Grained Token:

1. Go to GitHub Token Settings
2. Click "Generate new token" → "Fine-grained token"
3. Configure the token:
   • Token name: Stale Fork Manager
   • Expiration: 7 days (or custom short period)
   • Repository access: All repositories (or select specific ones)
   • Permissions:
     • Repository permissions → Administration: Read and write
4. Click "Generate token" and copy it
5. Paste the token into the application UI when prompted

🔒 Security Best Practice: Use short expiration periods (7-30 days) and regenerate tokens regularly.

Option 2: OAuth App (For Shared Deployments)

1. Navigate to GitHub Developer Settings
2. Click "New OAuth App"
3. Configure the application:
   • Application name: Stale Fork Manager (or your choice)
   • Homepage URL: http://localhost:3000
   • Authorization callback URL: http://localhost:3000/auth/github/callback
4. Click "Register application"
5. Note your Client ID
6. Generate and note your Client Secret

⚠️ Important: The callback URL must match exactly, including the /auth/github/callback path.

2. Configure Environment Variables

Create a .env file in the project root:

Minimum configuration (PAT only):

# Required: Session secret (generate a random string)
SESSION_SECRET=your_random_session_secret_here

Full configuration (with OAuth):

# Required: Session secret
SESSION_SECRET=your_random_session_secret_here

# Optional: GitHub OAuth credentials (leave blank to use PAT only)
GITHUB_CLIENT_ID=your_client_id_here
GITHUB_CLIENT_SECRET=your_client_secret_here

# Optional: Base URL for production
# BASE_URL=https://your-domain.com

# Optional: Node environment
# NODE_ENV=production

Generate a secure session secret:

node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

3. Install Dependencies

npm install

4. Run the Application

Development mode (with hot reload):

npm run dev

Production mode:

npm start

The application will be available at http://localhost:3000

5. Using the Application

With Personal Access Token:

1. Authenticate: Paste your fine-grained token in the input field and click "Authenticate"
2. Configure: Adjust the staleness threshold (default: 180 days)
3. Filter: Apply visibility and archived filters as needed
4. Select: Check the forks you want to manage
5. Archive: Click "Archive Selected" to archive (reversible)
6. Delete: Click "Delete Selected" and type "DELETE" to confirm (permanent)

With OAuth:

1. Login: Click "Login with GitHub" on the landing page
2. Authorize: Grant the requested permissions (repo, delete_repo)
3. Follow steps 2-6 above

API Endpoints

Authentication

• GET /auth/github - Initiate OAuth flow
• GET /auth/github/callback - OAuth callback handler
• GET /api/user - Get authenticated user info
• POST /api/logout - Destroy session

Stale Forks

• GET /api/forks/stale - List stale forks with filters
  • Query params: daysThreshold, visibility, includeArchived
• POST /api/forks/archive - Archive repositories (bulk)
  • Body: { "repoIds": [123, 456] }
• POST /api/forks/delete - Delete repositories (bulk)
  • Body: { "repoIds": [123, 456] }

Rate Limiting

GitHub API rate limits:

• Authenticated: 5,000 requests/hour
• Unauthenticated: 60 requests/hour

The application:

• Shows remaining rate limit when exceeded
• Displays wait time from GitHub response headers
• Does not retry automatically - user decides when to retry

License

MIT