Skip to content

GitHub App Setup

This guide explains how to create and configure a GitHub App to enable all GitPulse functionality.

Overview

GitPulse uses a GitHub App to access repository data, analyze commits, pull requests, deployments, and other GitHub events. The GitHub App provides secure, scoped access to your repositories without requiring full user account access.

Creating a GitHub App

1. Go to GitHub App Settings

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

2. Basic Information

Fill in the basic information:

  • GitHub App name: GitPulse (or your preferred name)
  • Description: GitHub Analytics Dashboard for CTOs and Tech Leads
  • Homepage URL: Your GitPulse instance URL (e.g., https://yourdomain.com)
  • Webhook: Leave unchecked (GitPulse doesn't use webhooks)

3. Repository Access

  • Repository access: Choose "All repositories" for full access, or "Only select repositories" to limit access
  • Installation target: Select the account or organization where you want to install the app

4. Permissions

Set the following permissions to enable all GitPulse features:

Repository Permissions

Permission Access Required For
Contents Read Repository content analysis, commit history
Metadata Read Repository information, topics, description
Pull requests Read PR analysis, review times, merge patterns
Issues Read Issue tracking, resolution times
Discussions Read Community engagement metrics
Actions Read CI/CD pipeline analysis, workflow runs
Deployments Read Deployment frequency, environment tracking
Environments Read Environment-specific deployment data
Security events Read Security alerts, vulnerability scanning

User Permissions

Permission Access Required For
Email addresses Read Developer identification, commit attribution

5. Create the GitHub App

Click "Create GitHub App" to complete the setup.

How GitPulse Uses the GitHub App

Data Retrieval Method

GitPulse does NOT use webhooks or real-time event subscriptions. Instead, it:

  • Makes scheduled API calls to GitHub to retrieve repository data
  • Polls the API at regular intervals to get the latest information
  • Uses the GitHub App's permissions to access repository data when needed
  • Stores data locally for analysis and reporting

Why No Webhooks?

  • Simpler setup: No need to configure webhook endpoints
  • More reliable: No dependency on external webhook delivery
  • Better control: GitPulse decides when to fetch data
  • Easier maintenance: No webhook URL management or SSL certificates

Installing the GitHub App

1. Install on Account/Organization

  1. After creating the app, you'll be redirected to the installation page
  2. Click "Install" to install the app on your account or organization
  3. Choose which repositories to grant access to

2. Get Installation Credentials

After installation, you'll need these credentials for GitPulse:

  • App ID: Found in your GitHub App settings
  • Installation ID: Found in the installation URL or settings
  • Private Key: Download from your GitHub App settings

Configuration in GitPulse

1. Web Interface Configuration

GitPulse uses a web-based configuration wizard instead of environment variables. After creating your GitHub 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

Security Considerations

1. Repository Access

  • All repositories: Provides access to all repositories in the account/organization
  • Selected repositories: Limits access to only specified repositories
  • Public repositories: Only provides access to public repositories

2. Permission Scope

  • GitPulse only requests read permissions
  • No write access to repositories, issues, or pull requests
  • No access to user account data beyond what's publicly visible

3. Token Security

  • Private keys are stored securely and never exposed in logs
  • Installation tokens are automatically rotated by GitHub
  • Access can be revoked at any time from GitHub settings

Troubleshooting

Common Issues

  1. Permission denied errors: Ensure all required permissions are granted
  2. Repository not found: Check that the repository is included in the installation
  3. Rate limiting: GitHub Apps have higher rate limits than personal access tokens
  4. Webhook configuration: NOT required - GitPulse uses API calls, not webhooks

Rate Limits

GitHub Apps have the following rate limits:

  • Repository API: 5,000 requests per hour per repository
  • Search API: 1,000 requests per hour
  • GraphQL API: 5,000 points per hour

Support

If you encounter issues:

  1. Check the GitHub App documentation
  2. Verify permissions and installation settings
  3. Check GitPulse logs for specific error messages

Next Steps

After setting up your GitHub App:

  1. Configure GitPulse with your app credentials
  2. Set up incident webhooks for monitoring
  3. Start analyzing your repositories