If you want a reliable delivery dashboard, start with the connection and mapping steps. In practice, a good GitHub engineering metrics setup is usually just three decisions: how you connect GitHub, which teams and repos you scope, and what you need to verify before pilot use.
This guide walks through that path in plain terms, so you can avoid the common setup stalls and get to useful data faster.
1. Start with the connection model
DeliveryCompass supports a read-only GitHub App install and OAuth connection, with a daily sync cadence. That means you can connect without changing developer workflows, and your dashboard will refresh on a regular schedule.
Before you begin, confirm who will complete the connection, which GitHub organization or account is in scope, and whether you want to start with one team or a broader pilot. If you need the higher-level flow first, see how it works and the setup guide.
What to verify up front
- You can access the GitHub org or the selected repositories.
- You know whether the install should cover all repos or a subset.
- You have a clear owner for the pilot setup.
2. Map teams and repos before you look at metrics
One of the fastest ways to slow down setup is to open the dashboard before your team-to-repo mapping is clean. Scoped KPIs only make sense when the right teams and repos are connected to each view.
Use teams and repos as the anchor for this step. A small, explicit mapping is better than a broad one that mixes unrelated work. If you are deciding which delivery measures belong in scope, the choosing delivery metrics page can help you avoid overloading the setup.
A simple mapping checklist
- List the team or pilot group.
- List the repos they primarily own.
- Exclude shared or out-of-scope repos for the first pass.
- Confirm the mapping with the team owner before reviewing charts.
3. Know what the first dashboard should show
Once the connection and mapping are in place, the overview dashboard gives you team KPIs, trend charts, and a team performance table. That is the fastest way to check whether the setup is producing data that matches your expectations.
If you want a deeper view, the dashboard page explains how the overview works. You can also move into team analytics when you need chart-by-chart detail, or use chart milestones to mark important changes during a pilot.
What to look for first
- Are the expected teams showing up?
- Do the repos match the intended scope?
- Do trend charts reflect the time period you expected?
- Does the team performance table line up with the team you mapped?
4. Use the weekly summary to validate the pilot
The weekly summary is useful early because it gives you a lightweight way to confirm that the data is readable enough for staff meetings. Attention callouts can surface items worth discussing without making you dig through every chart.
For the practical format, see weekly summary. If you are preparing a recurring leadership review, staff meeting metrics can help you keep the meeting focused on a few useful signals instead of too many charts.
Good pilot questions to ask
- Are the callouts describing real changes in the team’s work?
- Do the numbers feel scoped to the right repos?
- Is there enough clarity to use this in a weekly meeting?
5. Check contributor signals and read-only behavior
After the first sync, you can review contributor coaching signals derived from GitHub PR metadata. These signals help managers spot patterns through engineering intelligence for GitHub PR delivery without asking engineers to maintain a separate reporting process.
For a practical explanation of what those signals represent, see profile and code review responsiveness. If your team wants to understand the broader PR flow context, PR flow for engineering teams is a useful follow-up.
Because the connection is read-only, the main setup risk is not access changes; it is scope. If the repo mapping is too broad, the metrics will be harder to trust.
6. When setup does not look right, troubleshoot the scope first
When a dashboard looks incomplete, the cause is often a mapping issue rather than a connection failure. Start by checking the selected repos, the team scope, and whether the sync has had time to complete.
The troubleshooting page covers common setup issues, and limitations is worth reviewing before a pilot so expectations stay realistic. If you are specifically running a pilot, make sure you understand pilot limitations before deciding whether the current setup is ready for wider use.
Common early checks
- Was the right GitHub org connected?
- Were the intended repos included in the mapping?
- Has the daily sync had time to populate the dashboard?
- Are you comparing the right team and time window?
FAQ
How long does GitHub setup usually take?
It depends on how quickly you can confirm the connection owner, the org or repo scope, and the team-to-repo mapping. A small pilot is usually faster than a broad rollout because there are fewer scope decisions to resolve.
Should I start with all repos or one team?
Start with one team if your goal is to validate the setup quickly. A narrower scope makes it easier to tell whether the connection and mapping are correct before expanding to more repos.
Why does my dashboard not match what I expected?
The most common cause is scope. Recheck the team and repo mapping, then confirm the daily sync has completed. If the issue persists, use the troubleshooting guide to narrow it down.
Do I need to change how engineers work to get started?
No. The connection is read-only, so the setup is focused on choosing the right scope and verifying the first useful dashboard.
What should I review before a pilot meeting?
Review the overview dashboard, the weekly summary, and the team mapping. That combination is usually enough to tell whether the pilot is ready for a broader audience.
If you are ready to begin, start the connection and mapping flow in /app/onboarding.