If you want reliable GitHub PR delivery metrics, start with the connection path: install the GitHub App or connect with OAuth, then map the right teams and repositories before you look at charts. That sequence keeps the first dashboard useful instead of noisy.
This guide walks through the practical setup steps engineering managers usually need: what to connect, how daily sync works, how to scope metrics, and what to check when the pilot feels off. For the core product flow, see how it works and the setup page.
1. Choose the connection path that matches your policy
DeliveryCompass supports a read-only GitHub App install and OAuth. Both are designed to pull GitHub PR metadata without changing your repositories.
- GitHub App install: a good fit when you want a clearer permissions model and a standard install flow.
- OAuth connection: useful when your org prefers user-based authorization for the first connection.
In both cases, the goal is the same: connect once, then let the daily sync keep your dashboard current. If you want the overview of what shows up after connection, review the dashboard page.
2. Connect GitHub, then confirm what data is in scope
After the initial connection, check that the expected organizations, teams, and repositories are included. The most common setup issue is not the connection itself, but an incomplete scope.
- Install or authorize GitHub access.
- Verify the org and repository list that was included.
- Confirm which teams should be tracked.
- Wait for the first daily sync before judging the results.
If you are planning a pilot, the pilot limitations page is worth reading before you expand the setup. It helps set expectations around what is available during the first pass.
3. Map teams and repositories before you compare metrics
Scoped KPIs depend on clean team-to-repo mapping. If a team owns only part of a repo set, or shares repos with another group, map that explicitly before you compare trends across teams.
The teams and repos guide explains how scoped KPIs are organized. A simple rule helps here: if a team would not recognize the work as theirs, do not include it in their primary scope.
- Map one team to the repos it actively ships from.
- Avoid broad org-wide mappings for pilot views.
- Review shared repos separately so they do not blur team comparisons.
4. Use the first dashboard as a validation step, not a report card
Once sync completes, use the overview dashboard to validate the setup. Check whether team KPIs, trend charts, and the team performance table line up with what you already know about current work patterns.
The point of the first view is to spot setup issues early:
- Do the teams shown match your intended scope?
- Are the trends based on enough history to be meaningful?
- Do the numbers look consistent with recent delivery activity?
If you want to go deeper by chart, the team analytics page and chart milestones page show how drill-downs and milestone markers support follow-up conversations.
5. Add the weekly summary once the base connection is stable
After the connection and mapping are in place, the weekly summary gives you a lightweight way to bring delivery signals into staff meetings. It is usually more useful after the scope is clean, because attention callouts work best when they reflect the right teams and repos.
See the weekly summary page for what appears in that view, and use the staff meeting metrics guide for a practical meeting format.
6. Troubleshoot the usual setup friction fast
When a setup feels incomplete, the cause is often one of three things: missing repo access, unmapped teams, or waiting for the first sync to finish. Start with those before assuming the connection failed.
- Missing repos: confirm the GitHub install or OAuth grant included the right repositories.
- Unexpected teams: review your team mapping and remove overlap where possible.
- No recent data: daily sync means new connections may not populate immediately.
If you need a checklist for common issues, use troubleshooting. For broader product questions, the FAQ and limitations pages are the next stops.
FAQ
How long does it take to see data after connecting GitHub?
After the initial connection, data appears after the daily sync runs. If you have just installed the app or authorized OAuth, give the system time to complete the first refresh before checking results.
Why do my team metrics look broader than expected?
That usually means the team-to-repo mapping is wider than intended. Review the teams and repos setup and narrow the scope to the repos the team actually owns.
Can I use the dashboard before every repo is mapped?
Yes, but treat the first view as a validation pass. Partial mapping can be useful for a pilot, but it is not the right basis for team comparisons until the scope is settled.
Where should I start if the connection does not look right?
Start with setup, then check troubleshooting. If the issue is about what is included in your pilot, review pilot limitations.
Ready to set up your first scoped view? Start at onboarding and follow the connection, mapping, and validation steps in order.
engineering intelligence for GitHub PR delivery