The GitHub Permission Mistake That Gets Security Rejected

Before connecting any engineering analytics tool to your GitHub organization, you need to understand exactly what access you're granting. This guide explains GitHub OAuth scopes and app permissions, helps you choose between OAuth Apps and GitHub Apps, and provides security best practices for analytics integrations.

For broader security and compliance considerations, see our Security & Compliance Guide for GitHub Analytics.

Understanding GitHub OAuth Scopes

What Are OAuth Scopes?

OAuth scopes define what an application can access when you authorize it. Each scope grants specific permissions. When you see an authorization screen listing scopes, you're seeing exactly what the app will be able to do.

Common Scopes for Analytics Tools

Engineering analytics tools typically need these scopes:

OAuth Scopes for Analytics

Scope: repo

What it grants: Read access to code, commits, pull requests
What it grants: Read access to issues and projects
What it grants: Read access to repository metadata
Why analytics needs it: Read PR data (open, merged, cycle times)
Why analytics needs it: Read commit history and review comments
Why analytics needs it: Read status checks and CI results

Scope: read:org

What it grants: Read organization membership
What it grants: Read team membership
What it grants: Read organization settings (limited)
Why analytics needs it: Know which repos belong to your org
Why analytics needs it: Identify team members and filter by organization

Scope: read:user

What it grants: Read user profile information
What it grants: Read user email addresses
Why analytics needs it: Display contributor names/avatars
Why analytics needs it: Match commits to users and build developer profiles

Scopes Analytics Should NOT Need

Be suspicious if an analytics tool requests these:

write:repo_hook: Can create webhooks (read-only analytics doesn't need this)
delete_repo: Can delete repositories (never needed)
admin:org: Can manage organization settings (never needed)
write:org: Can modify organization membership (never needed)
admin:repo_hook: Can manage webhooks (excessive for analytics)

Detect code hotspots and knowledge silos with CodePulse

OAuth App vs GitHub App: Which to Choose

OAuth Apps

OAuth Apps are the traditional way to authorize third-party access:

How they work:

User authorizes the app with their personal GitHub account
App acts on behalf of that user
Access is tied to the authorizing user's permissions

Pros:

Simple setup—just click authorize
Works immediately across all orgs the user can access
No organization admin approval required (in most cases)

Cons:

Access tied to individual user (what if they leave?)
Harder for admins to audit and control
Broader scopes than might be necessary

GitHub Apps

GitHub Apps are the newer, more granular approach:

How they work:

Installed at the organization level by an admin
App has its own identity, not tied to a user
Granular permissions per repository

Pros:

More granular permissions (read-only by default)
Org-level control—admins can manage centrally
Survives employee turnover
Better audit trail

Cons:

Requires organization admin to install
More complex setup process
May need to select specific repositories

Recommendation

Which Should You Choose?

Choose OAuth App if...

You need quick setup for evaluation
You're a small team with simple needs
Org admin isn't available to approve

Choose GitHub App if...

Security/compliance is a priority
You want org-level control
You need to limit access to specific repos
You're deploying across multiple orgs

Minimum Permissions for Analytics

What Analytics Actually Needs

A well-designed analytics tool should need only read access:

GitHub App Permissions (Minimal Set)

Repository Permissions

Contents: Read (to read commits)
Pull requests: Read (to read PR data)
Checks: Read (to read CI status)
Metadata: Read (always required)

Organization Permissions

Members: Read (to see org membership)

User Permissions

Email addresses: Read (optional, for user matching)

Important Note

NO write permissions should be required for pure analytics

🔐What CodePulse Requires

CodePulse uses a GitHub App with the minimum read-only permissions listed above. We never request write access to your repositories. During setup, you'll see exactly which permissions are requested before authorizing. You can also limit access to specific repositories rather than your entire organization.

Learn more about CodePulse's security model →

Webhook Events (If Used)

Some analytics tools use webhooks for real-time updates:

Pull request events: Notified when PRs are opened, closed, merged
Pull request review events: Notified when reviews are submitted
Push events: Notified when code is pushed
Check run events: Notified when CI checks complete

Webhooks don't grant additional access—they just notify the app when things happen. The app still needs read permissions to fetch the actual data.

Detect code hotspots and knowledge silos with CodePulse

Security Best Practices

Before Authorizing

Verify the app: Is it from a known vendor? Does the URL match their official site?
Review scopes carefully: Does the app need everything it's requesting?
Check vendor security: Do they have a security page? SOC 2? See our Security & Compliance Guide
Understand data handling: Where is your GitHub data stored? Who can access it?

After Authorizing

Audit regularly: Review authorized apps in GitHub Settings → Applications
Revoke unused apps: Remove access for tools you no longer use
Monitor access: GitHub's audit log shows app activity (on Enterprise plans)
Update when needed: Re-authorize if the vendor changes scopes

Organizational Controls

For GitHub organizations, admins can control third-party access:

Organization Settings to Review

Settings > Third-party access

OAuth App access policy: Require admin approval
GitHub App installations: Review and approve
SAML/SSO requirements: Can require SSO for app access

Settings > Audit log (Enterprise)

Track app authorizations
Monitor data access patterns
Alert on suspicious activity

Token Security

When analytics tools store tokens:

Encryption at rest: Tokens should be encrypted in the vendor's database
Limited exposure: Tokens shouldn't be visible in UIs or logs
Rotation capability: You should be able to revoke and re-authorize
Minimal storage: Ideally, only access tokens stored (not refresh tokens forever)

Multi-Organization Setup

Personal vs Organization Accounts

GitHub has two account types that affect analytics setup:

Personal accounts: Individual developers with personal repos
Organization accounts: Teams with shared repos and membership

Most analytics tools focus on organizations, where team metrics make sense.

Multiple Organizations

If you have multiple GitHub organizations:

Multi-Org Setup Options

Option 1: Single Authorizing User

One person authorizes across all orgs they can access
Simpler setup
Risk: Access depends on that person's membership

Option 2: Per-org GitHub App Installation

Each org admin installs the app
Better isolation and control
More setup work

Option 3: Separate Analytics Accounts per Org

Complete isolation between orgs
Best for unrelated orgs (e.g., different companies)
Most overhead

Enterprise GitHub

GitHub Enterprise (Cloud or Server) adds considerations:

Enterprise-level app management: Can approve apps across all orgs
SAML/SSO integration: Apps may need to work with your IdP
IP allowlisting: Analytics vendor IPs may need to be allowed
Audit requirements: Enterprise plans have better logging for compliance

Troubleshooting Access Issues

Common problems and solutions:

Troubleshooting Guide

Problem: "Not seeing all my repositories"

Check if app has access to private repos
Verify org hasn't restricted third-party access
Re-authorize with broader scope if needed

Problem: "Access suddenly stopped working"

Token may have expired - re-authorize
User who authorized may have lost access
Org admin may have revoked app access

Problem: "Getting rate limited"

GitHub limits API calls per token
Analytics tool should handle this gracefully
Consider GitHub App (higher limits) vs OAuth App

Revoking Access

To remove an analytics tool's access:

User level: Settings → Applications → Authorized OAuth Apps → Revoke
Org level (OAuth App): Org Settings → Third-party access → Remove
Org level (GitHub App): Org Settings → Installed GitHub Apps → Uninstall

Revoking access immediately stops the app from making new API calls. Any cached data remains with the vendor per their data retention policy.

For a comprehensive tool comparison including permission requirements, see our Engineering Analytics Tools Comparison.