If you want GitHub engineering metrics setup to be useful on day one, start with a clean connection, then verify your team and repo mapping before you treat the numbers as report-ready. The fastest path is straightforward: install the GitHub App or connect with OAuth, let the daily sync complete, and confirm the dashboard is scoped to the teams you manage.
This guide walks through the setup flow in practical terms, with the checks that prevent most pilot friction. If you hit a setup edge case, the limits and troubleshooting docs are worth reading early: pilot limitations, setup, troubleshooting, and teams and repos.
1) Start with the connection model
DeliveryCompass supports a read-only GitHub App install and OAuth connection, both designed to pull GitHub PR metadata without changing your GitHub data. For most teams, the main decision is less about features and more about access: which orgs, teams, and repos should be in scope for the first dashboard.
Before you connect, make sure you know who owns the GitHub organization, who can approve the install, and which repos should be included in the pilot. That small amount of prep avoids the most common back-and-forth during setup.
What to confirm before you connect
- The GitHub org or orgs you want to include
- Whether you need a single team pilot or broader coverage
- Which repos should be included in the first metrics view
- Who will validate the results after the initial sync
2) Install or authorize GitHub, then let sync finish
The connection step is intentionally simple: install the GitHub App or complete the OAuth authorization, then wait for the first daily sync. The dashboard does not become meaningful until GitHub data has had time to flow in and be processed into team KPIs, trend charts, and the team performance table.
For setup details, follow the steps in setup. If the org install is blocked, or if you’re not seeing expected data after authorization, check troubleshooting before redoing the connection.
Practical sync check
- Complete the GitHub connection
- Wait for the first daily sync to finish
- Open the dashboard and look for populated team KPIs
- Confirm trend charts are updating from GitHub PR metadata
3) Map teams and repos before you read the dashboard
Good metrics depend on scope. If the wrong repos are attached to a team, the dashboard can look busy without being useful. The teams and repos setup is the part that makes scoped KPIs hold up in review meetings, because it tells the system which work belongs to which team.
Use the first pass to map only what you are confident about. You can expand scope later, but starting narrow makes it easier to validate lead time, review responsiveness, and throughput patterns without mixing unrelated work.
Recommended mapping approach
- Start with one team and a clearly owned repo set
- Exclude shared repos until ownership is understood
- Check that each repo maps to the intended team
- Revisit the mapping after the first week of data
4) Validate the first dashboard views
Once the sync is complete and the mapping looks right, review the dashboard in three layers: overview, trends, and drill-down. The overview dashboard gives you team KPIs and the performance table; the chart grid shows deeper patterns; and the drill-down helps you verify whether the metric reflects real delivery behavior or just a scope issue.
If you want a quick tour of what should be visible, see dashboard and team analytics. For chart behavior and milestone markers, chart milestones is the reference.
What “good enough to review” looks like
- Team KPIs are populated for the expected teams
- Trend lines show movement across recent periods
- The team performance table matches your intended scope
- Drill-downs explain the chart instead of creating new confusion
5) Use the first week to catch setup issues early
Most setup problems show up as scope problems, not connection failures. A team may appear to have low throughput, but the real issue is that not all repos were mapped. Or a trend may look flat because the pilot is too narrow to be representative yet. That is why the first week should be treated as validation, not a final scorecard.
Read the limitations page to understand what the pilot does and does not cover. If you are using the dashboard for a staff meeting or manager review, pair the dashboard with the weekly summary so you can spot attention callouts before the meeting starts.
Common early checks
- Are all intended repos included?
- Are any shared repos inflating or diluting the team view?
- Does the dashboard reflect the same team boundaries you use internally?
- Do the numbers make sense next to recent PR activity in GitHub?
6) Turn the connection into a repeatable operating rhythm
A connected dashboard is most useful when it becomes part of a regular review cadence. Many managers start with one team, confirm the data, then expand the mapping once they trust the baseline. That keeps the setup manageable and makes it easier to use the dashboard for coaching, planning, and staff meeting prep.
This kind of operating rhythm is part of engineering intelligence for GitHub PR delivery, especially when you want team reviews to stay grounded in GitHub PR metadata and practical follow-up. For teams looking to tighten their review habits, the broader guides on GitHub metrics for managers and PR flow for engineering teams are helpful next reads after setup.
When you are ready to begin, use the onboarding flow at /app/onboarding to connect GitHub and set your first team scope.
FAQ
How long does the first GitHub sync take?
After you complete the GitHub App install or OAuth authorization, the first daily sync needs time to finish before the dashboard reflects current data. If the dashboard still looks empty afterward, start with troubleshooting.
Should I map all repos at once?
No. A narrow pilot is usually easier to validate. Start with one team and the repos it clearly owns, then expand scope after you confirm the metrics line up with your GitHub activity and internal team boundaries.
Why does the dashboard look different from what I expected?
In most cases, the issue is mapping rather than the connection itself. Review teams and repos and confirm the intended repos are assigned to the right team before adjusting your interpretation of the charts.
What should I check before sharing metrics in a meeting?
Confirm the team scope, review the first trend charts, and scan the weekly summary for attention callouts. The weekly summary can help you catch issues before the discussion starts.
Where can I see the product areas covered by setup?
Use product tour for a quick overview, then review dashboard, team analytics, and metrics for the pieces that matter most after connection.