Connect your first integration

Connecting GitHub is the fastest path to seeing value in Koalr. Within 15 minutes of completing OAuth you will have deploy risk scores, PR metrics, and CODEOWNERS data flowing into your dashboards.

Prerequisites

• You must be an organization admin in both Koalr and your GitHub organization. Koalr needs to register an organization-level webhook, which requires admin access.
• Your GitHub organization must allow OAuth app access. If your org enforces OAuth app restrictions, an owner will need to approve Koalr before the connection can complete.

Navigating to Settings → Integrations

1. Log in to Koalr and open the left sidebar.
2. Click Settings near the bottom of the navigation.
3. Select Integrations from the settings submenu.

You will see a list of available integrations. GitHub appears at the top of the list with a Connect button.

Starting the OAuth flow

Click Connect GitHub. Koalr will redirect you to GitHub's OAuth authorization page.

OAuth scopes we request

Koalr requests the following scopes during the GitHub OAuth flow:

Scope	Why we need it
read:org	Read team membership and organization details so Koalr can map contributors to teams
read:user	Read the authenticated user's profile (name, avatar, email)
repo	Read pull requests, commits, branches, and file contents including CODEOWNERS
admin:repo_hook	Register webhooks at the organization level to receive real-time push, PR, and deployment events

Koalr only ever reads from GitHub — we never push commits, create issues, or modify repository settings beyond webhook registration.

After you authorize

Once you click Authorize on GitHub, you are redirected back to Koalr's integrations page. The following happens automatically:

1. Webhook registration (< 30 seconds)

Koalr registers a single organization-level webhook at https://api.koalr.com/webhooks/github. This webhook receives:

• Push events (for CODEOWNERS sync and coverage correlation)
• Pull request events (for PR metrics and deploy risk scoring)
• Deployment events (for deploy outcome tracking)

If webhook registration fails (most commonly due to insufficient org admin permissions), you will see an error banner in the integrations settings with a Retry webhook registration button.

2. Initial repository sync (5–15 minutes)

Koalr immediately enqueues a background sync job that crawls your organization's repositories. For organizations with fewer than 100 repositories, this typically completes in 5 to 15 minutes. For larger organizations (500+ repos), expect up to 60 minutes for the initial crawl.

During the initial sync, Koalr:

• Indexes all repositories and their default branches
• Imports the last 90 days of pull requests
• Reads CODEOWNERS files from .github/CODEOWNERS, CODEOWNERS, and docs/CODEOWNERS in each repository
• Fetches the last 90 days of commits for churn and authorship analysis

3. Fast-path risk scores (60 seconds)

Before the full sync completes, Koalr generates an initial deploy risk score for each repository using the data available. These scores become more accurate as the sync completes and historical PR and commit data is loaded.

Verifying the connection

Once connected, return to Settings → Integrations → GitHub. You will see:

• A green Connected badge next to the integration
• The GitHub organization name and the authenticated user
• Webhook status (Active or Failed)
• Repository count discovered so far (updates as sync progresses)

What to do next

After GitHub is connected, most teams connect either Jira or Linear next to add sprint and issue cycle time data to their DORA metrics. You can also connect Slack to receive CODEOWNERS drift alerts and weekly digest notifications.

If repositories are not appearing after 20 minutes, see Data not showing up or GitHub permissions troubleshooting.