GitHub Permissions

This page covers the GitHub permissions Koalr requires, the exact OAuth scopes requested during authorization, and how to resolve issues caused by connecting with insufficient permissions.

OAuth App vs GitHub App

Koalr uses a GitHub OAuth App (not a GitHub App) for its GitHub integration. The key difference:

• OAuth App — authenticates as the user who authorized the connection. Koalr can access repositories that the authorizing user has access to. Webhook registration is done via the GitHub API using the user's token.
• GitHub App — authenticates as the app itself, with permissions granted at the organization level by an owner.

Because Koalr uses an OAuth App, the user who completes the OAuth authorization must be an organization admin for webhook registration to succeed. If a non-admin user connects GitHub, PR and commit data can be read, but the organization-level webhook cannot be registered.

OAuth scopes requested

Koalr requests the following GitHub OAuth scopes:

read:org

Why we need it: Read access to organization membership information, including which users belong to which teams. This scope is required for Koalr to map GitHub contributors to your organization's team structure and populate team-level metrics.

Without this scope, Koalr cannot read GitHub team membership and team-level metrics will show all contributors as ungrouped.

read:user

Why we need it: Read the authenticated user's public profile information — name, avatar, and primary email. This is used to create or update the Koalr user record for the person who authorized the connection.

repo

Why we need it: Read pull requests, commits, branch information, file contents, and commit statuses for private and public repositories. This is the broadest scope Koalr requests and is necessary because:

• Pull request data (titles, authors, reviews, merge status) requires repo-level access
• Commit history and blame data for coverage correlation and churn analysis require repo access
• CODEOWNERS file contents are read from the repository using this scope
• Posting GitHub Check Runs (for CODEOWNERS enforcement) requires repo access

Koalr only reads from repositories. We do not push commits, create branches, merge PRs, or modify any repository content.

admin:repo_hook

Why we need it: Create and manage organization-level webhooks. This scope is what allows Koalr to register the webhook at https://api.koalr.com/webhooks/github that delivers real-time push, pull request, and deployment events.

This scope requires the authorizing user to be an organization admin. If the connecting user does not have this access level, webhook registration will fail. See Webhook Setup Troubleshooting if this happens.

Organization admin requirement

For full Koalr functionality, the GitHub user who completes the OAuth authorization must have organization admin (owner) access in your GitHub organization. This is required specifically for:

• Registering the organization-level webhook (admin:repo_hook)
• Reading all teams and team memberships within the organization (read:org on some private org structures)

If a non-admin engineer connected GitHub and webhook registration failed, an org admin must reconnect the integration. The non-admin connection can be disconnected from Settings → Integrations → GitHub → Disconnect, and the org admin can then reconnect.

What to do if you connected with insufficient scopes

GitHub OAuth tokens carry the scopes that were granted at the time of authorization. If the Koalr connection was made by a user without admin access, or if scopes were denied during the OAuth flow, Koalr's token may be missing required permissions.

Symptom indicators:

• Webhook status shows Failed to register in Settings → Integrations → GitHub
• Team membership is not being read (all contributors appear ungrouped)
• CODEOWNERS files not being synced

Resolution — reconnect with correct scopes:

1. Go to Settings → Integrations → GitHub.
2. Click Disconnect.
3. Log in to GitHub (or switch to) the organization admin account.
4. In Koalr, click Connect GitHub and complete the OAuth flow, approving all requested scopes.
5. Koalr will re-register the webhook and re-sync repository data.

If your org restricts OAuth app access:

Some GitHub organizations require an owner to approve OAuth apps before members can authorize them. If you see an error during the OAuth flow saying Koalr is not authorized for your organization:

1. A GitHub organization owner must go to Organization Settings → Third-party access → OAuth App access policy.
2. Find Koalr in the pending approval list and click Approve.
3. Once approved, re-attempt the connection from Koalr.

Revoking Koalr's access

To remove Koalr's GitHub access entirely:

1. Disconnect GitHub in Settings → Integrations → GitHub → Disconnect (removes the webhook from your GitHub org).
2. Go to your GitHub account Settings → Applications → Authorized OAuth Apps.
3. Find Koalr and click Revoke to remove the token.

Revoking the token without disconnecting in Koalr first will cause the integration to show as failed until it is explicitly disconnected.