Skip to content

GitHub Setup Overview

This guide provides a clear overview of the two different GitHub applications you need to set up for GitPulse and their distinct purposes.

Two Apps, Two Purposes

GitPulse requires two separate GitHub applications to function properly:

  1. GitHub App - For data access and functionality
  2. OAuth App - For user authentication (SSO)

Quick Comparison

Aspect GitHub App OAuth App
Purpose Repository data access User authentication
Required for All GitPulse features Login only
Permissions Repository read access User profile only
What it enables Analytics, metrics, insights SSO login
Setup complexity Moderate Simple

GitHub App

What It Does

  • Accesses repository data (commits, PRs, deployments)
  • Enables all GitPulse analytics features
  • Provides higher API rate limits
  • Scoped access to specific repositories

When You Need It

  • ✅ Repository analysis
  • ✅ DORA metrics calculation
  • ✅ Security scanning
  • ✅ Deployment tracking
  • ✅ Team performance insights

Setup Required

OAuth App

What It Does

  • Handles user login and authentication
  • Provides Single Sign-On (SSO) experience
  • Manages user access to GitPulse
  • No repository data access

When You Need It

  • ✅ User authentication
  • ✅ Team access management
  • ✅ SSO integration
  • ❌ Repository data (requires GitHub App)

Setup Required

Setup Order

1. Start with OAuth App (Authentication)

  1. Create OAuth App in GitHub
  2. Get Client ID and Client Secret
  3. Configure in GitPulse web interface

2. Then GitHub App (Functionality)

  1. Create GitHub App in GitHub
  2. Configure permissions and install on repositories
  3. GitPulse will use OAuth tokens for API access

Common Misconceptions

❌ "I only need OAuth App"

  • Reality: OAuth only provides login, no data access
  • Result: Users can log in but see no repository data
  • Solution: Must also set up GitHub App

❌ "I only need GitHub App"

  • Reality: GitHub App doesn't handle user authentication
  • Result: No way for users to log in
  • Solution: Must also set up OAuth App

❌ "They're the same thing"

  • Reality: Completely different purposes and permissions
  • Result: Confusion and incomplete setup
  • Solution: Understand and set up both separately

Complete Setup Checklist

OAuth App Setup ✅

  • [ ] Create OAuth App in GitHub
  • [ ] Configure callback URL
  • [ ] Set minimal scopes (read:user, user:email)
  • [ ] Get Client ID and Secret
  • [ ] Configure in GitPulse environment

GitHub App Setup ✅

  • [ ] Create GitHub App in GitHub
  • [ ] Configure repository permissions
  • [ ] Subscribe to required events
  • [ ] Install on target repositories
  • [ ] Get App ID, Installation ID, and Private Key
  • [ ] Configure in GitPulse environment

GitPulse Configuration ✅

  • [ ] Set all environment variables
  • [ ] Restart GitPulse service
  • [ ] Test user login (OAuth)
  • [ ] Test repository access (GitHub App)

Testing Your Setup

Test OAuth (Login)

  1. Navigate to GitPulse login page
  2. Click "Sign in with GitHub"
  3. Complete OAuth flow
  4. Verify successful login

Test GitHub App (Data)

  1. After OAuth login, try to access repositories
  2. Check if repository data loads
  3. Verify metrics and analytics appear
  4. Test specific features (DORA metrics, security scanning)

Troubleshooting Guide

OAuth Issues (Login Problems)

  • "Invalid redirect URI": Check callback URL configuration
  • "Application not found": Verify Client ID and Secret
  • "Insufficient scope": Ensure required scopes are granted

GitHub App Issues (Data Problems)

  • "Repository not found": Check GitHub App installation and permissions
  • "Permission denied": Verify repository access settings
  • "Rate limiting": Check GitHub App rate limits

Configuration Issues

  • "Environment variable not found": Verify all variables are set
  • "Service won't start": Check environment variable syntax
  • "Import errors": Ensure all required packages are installed

Next Steps

  1. Set up OAuth App for authentication
  2. Set up GitHub App for data access
  3. Configure GitPulse with both apps
  4. Start using GitPulse

Summary

  • Two apps required: GitHub App + OAuth App
  • Different purposes: Data access vs. authentication
  • Setup order: OAuth first, then GitHub App
  • Complete experience: Both needed for full functionality
  • Separate configuration: Each has its own setup process