Skip to content

OAuth App Setup

This guide explains how to set up a GitHub OAuth App for Single Sign-On (SSO) authentication in GitPulse.

Overview

Important: The OAuth App is used ONLY for user authentication (SSO). It does NOT provide access to repository data or enable GitPulse's core functionality.

For repository access and data analysis, you must also set up a GitHub App.

Purpose of OAuth App

The OAuth App serves a single purpose:

  • User Authentication: Allows users to sign in to GitPulse using their GitHub account
  • SSO Integration: Provides seamless login experience for your team
  • Access Control: Manages who can access your GitPulse instance

What OAuth App Does NOT Do

The OAuth App does NOT provide:

  • ❌ Repository data access
  • ❌ Commit history analysis
  • ❌ Pull request metrics
  • ❌ Deployment tracking
  • ❌ Security scanning
  • ❌ Any GitPulse analytics features

Creating an OAuth App

1. Go to GitHub OAuth App Settings

  1. Navigate to GitHub Settings > Developer settings > OAuth Apps
  2. Click "New OAuth App"

2. Basic Information

Fill in the basic information:

  • Application name: GitPulse SSO (or your preferred name)
  • Homepage URL: Your GitPulse instance URL (e.g., https://yourdomain.com)
  • Application description: Single Sign-On authentication for GitPulse
  • Authorization callback URL: https://yourdomain.com/accounts/github/login/callback/

3. Create the OAuth App

Click "Register application" to complete the setup.

OAuth App Permissions

Required Scopes

The OAuth App only needs minimal permissions for authentication:

Scope Access Purpose
read:user Read Access basic user profile information
user:email Read Access user's email addresses

What These Permissions Allow

  • read:user: Access to user's public profile (name, avatar, bio)
  • user:email: Access to user's email addresses for account creation

What These Permissions Do NOT Allow

  • ❌ Repository access
  • ❌ Code access
  • ❌ Organization membership details
  • ❌ Private repository information

Configuration in GitPulse

1. Web Interface Configuration

GitPulse uses a web-based configuration wizard instead of environment variables. After creating your OAuth App:

  1. Start GitPulse and navigate to the installation wizard
  2. Enter your OAuth App credentials:
  3. Client ID: From your GitHub OAuth App
  4. Client Secret: From your GitHub OAuth App
  5. Complete the installation through the web interface

2. OAuth App Credentials

After creating the OAuth App, you'll get: - Client ID: Public identifier for your app - Client Secret: Private key for authentication (keep secure)

Security Considerations

1. Limited Scope

  • OAuth App has minimal permissions
  • Cannot access repository data
  • Cannot perform actions on behalf of users

2. Authentication Only

  • Used solely for user login
  • No data access beyond user profile
  • Secure authentication flow

3. Token Security

  • Access tokens are short-lived
  • Stored securely in GitPulse
  • Automatically refreshed when needed

Complete Setup Requirements

To use GitPulse with full functionality, you need BOTH:

1. OAuth App (SSO Authentication)

  • ✅ User login and authentication
  • ✅ Team access management
  • ✅ Single sign-on experience

2. GitHub App (Data Access)

  • ✅ Repository data analysis
  • ✅ Commit history tracking
  • ✅ Pull request metrics
  • ✅ Deployment monitoring
  • ✅ Security scanning
  • ✅ All GitPulse features

Troubleshooting

Common OAuth Issues

  1. "Invalid redirect URI": Ensure callback URL matches exactly
  2. "Application not found": Verify Client ID and Secret
  3. "Insufficient scope": Ensure read:user and user:email scopes are granted

OAuth vs GitHub App Confusion

If you're experiencing issues:

  • "Repository not found": This is a GitHub App issue, not OAuth
  • "Permission denied": Check GitHub App permissions, not OAuth scopes
  • "Rate limiting": GitHub App rate limits, not OAuth limits

Testing OAuth Setup

1. Test Authentication

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

2. Verify Limited Access

After OAuth login, you should see: - ✅ User profile information - ✅ Email address - ❌ Repository data (until GitHub App is configured)

Next Steps

After setting up OAuth:

  1. Configure GitHub App for data access
  2. Set up GitPulse configuration
  3. Start using GitPulse features

Summary

  • OAuth App: Authentication only (SSO)
  • GitHub App: Data access and functionality
  • Both required: For complete GitPulse experience
  • Separate purposes: Don't confuse authentication with data access