Skip to main content

​
Overview

The GitHub integration provides rich source code context directly in your error tracking workflow. By connecting your GitHub repositories, Proliferate can:
  • Display original source code at error locations (with source maps)
  • Link directly to the exact line in GitHub where errors occurred
  • Access repository contents for enhanced debugging
  • Associate errors with specific commits and releases
Proliferate uses GitHub Apps (not OAuth Apps) for secure, installation-based access. This means no long-lived tokens are stored - instead, fresh tokens are generated on-demand with a 1-hour expiry.

​
What You Get

Source Code Context

View the exact source code where errors occurred, with surrounding context lines

Direct GitHub Links

Click through from errors directly to the relevant file and line in GitHub

Repository Access

Grant access to specific repositories for source fetching

Secure Token Management

Installation tokens are generated on-demand and expire after 1 hour

​
Setup Process

1

Navigate to Integrations

Go to Settings → Integrations in your Proliferate dashboard.
2

Install GitHub App

Click Install on the GitHub integration card. You’ll be redirected to GitHub to authorize the Proliferate App.
During installation, you can choose to grant access to all repositories or select specific ones. You can always modify this later in your GitHub settings.
3

Select Repositories

On the GitHub authorization page:
  • Select which repositories Proliferate can access
  • Choose between “All repositories” or “Only select repositories”
  • Click Install & Authorize
4

Complete Installation

You’ll be redirected back to Proliferate with a success confirmation. The GitHub integration will now show as Connected.
5

Configure Project Repositories

In your project settings, link your project to a specific GitHub repository. This enables source context features for that project.

​
How It Works

​
GitHub App Architecture

Proliferate uses the GitHub App model for secure, scalable access: 
┌─────────────┐
│  Proliferate│
│  Dashboard  │
└──────┬──────┘
       │
       │ 1. Install GitHub App
       ▼
┌─────────────────┐
│     GitHub      │
│  (Authorization)│
└──────┬──────────┘
       │
       │ 2. Returns installation_id
       ▼
┌─────────────────┐
│   Proliferate   │
│    Backend      │
│                 │
│  Stores only:   │
│  installation_id│
│  (NO token!)    │
└──────┬──────────┘
       │
       │ 3. On-demand: Generate JWT
       │ 4. Exchange for installation token
       │    (expires in 1 hour)
       ▼
┌─────────────────┐
│  GitHub API     │
│  (Fetch source) │
└─────────────────┘
Key Security Features:
  • No long-lived access tokens stored in the database
  • Installation tokens are generated fresh each time they’re needed
  • Tokens automatically expire after 1 hour
  • Organization-level access control via GitHub

​
Available GitHub Apps

EnvironmentApp NamePurpose
DevelopmentProliferate DevTesting and development
ProductionProliferate AppProduction usage

​
Permissions

The GitHub App requests these permissions:
Allows Proliferate to fetch source code files for error context. This is read-only and does not allow any modifications.
Access to basic repository information like name, description, and default branch.
Receive notifications about repository events like installation changes. Used to keep the integration status up-to-date.

​
Testing Your Connection

After installing the GitHub App, test your connection:
  1. Go to Settings → Integrations
  2. The GitHub card should show Connected status
  3. You’ll see basic information about accessible repositories
To verify source context is working:
  1. Ensure your project is linked to a GitHub repository
  2. Trigger an error in your application
  3. View the error detail page - you should see source code context and a link to GitHub

​
API Endpoints

The GitHub integration provides these endpoints:
EndpointMethodDescription
/api/v1/integrations/github/installGETStart GitHub App installation flow
/api/v1/integrations/github/app-callbackGETHandle installation callback
/api/v1/integrations/github/testGETTest connection and list repositories
/api/v1/integrations/github/repositoriesGETFetch all accessible repositories
/api/v1/integrations/github/webhookPOSTReceive GitHub webhooks

​
Troubleshooting

Checklist:
  • Is your project linked to a GitHub repository?
  • Have you uploaded source maps for the release?
  • Does the error event include a release field?
  • Does the GitHub App have access to the repository?
Ensure that:
  • You granted repository access during installation
  • The GitHub App installation includes the private repository
  • You can modify repository access in your GitHub organization settings
Installation tokens are generated on-demand and expire after 1 hour. If you see authentication errors:
  • Try the operation again (a fresh token will be generated)
  • Verify the GitHub App is still installed
  • Check that the app hasn’t been suspended in GitHub

​
Managing the Integration

​
Updating Repository Access

To modify which repositories Proliferate can access:
  1. Go to your GitHub organization settings
  2. Navigate to Installed GitHub Apps
  3. Find Proliferate App and click Configure
  4. Update repository access and save
Changes take effect immediately - no need to reconnect in Proliferate.

​
Disconnecting GitHub

To remove the integration:
  1. In Proliferate: Go to Settings → Integrations
  2. Click the disconnect icon on the GitHub card
  3. In GitHub: Optionally uninstall the app from your GitHub organization settings
Disconnecting GitHub will remove source code context from error detail pages. Existing errors will still be visible, but without GitHub links.

​
Best Practices

1

Link Projects to Repositories

Always configure the repository link in your project settings. This enables all source context features.
2

Upload Source Maps

Source maps are required for original source code context. Use the build plugins for automatic upload.
3

Use Release Versions

Ensure your SDK includes the release field matching your GitHub commit SHA or tag.
4

Grant Minimal Access

Only give the GitHub App access to repositories that contain application code you’re tracking.