If your dashboard feels “off,” the problem is often scope, not the metrics themselves. The fix is to map the right GitHub teams and repositories to the KPI set you want to track, then keep that mapping consistent as ownership changes.
For engineering managers, GitHub teams repos KPI mapping is the difference between a useful team view and a blended chart that nobody trusts. Here’s how to set up scoped KPIs so the data matches how your org actually works.
For engineering intelligence for GitHub PR delivery, start with the question the KPI should answer.
Start with the question the KPI should answer
Before you map anything, decide what decision the metric supports. A KPI for one team may not make sense for an entire org, and a repo-level metric may hide too much when the same codebase serves several teams.
- Use team-scoped KPIs when you need to compare delivery patterns across managers or squads.
- Use repo-scoped KPIs when a repository has a clear owner and the work stays mostly within one team.
- Use shared-scope KPIs when multiple teams contribute to the same codebase and you need a broader view.
If you want a refresher on metric selection, see /docs/choosing-delivery-metrics and /docs/metrics.
Map teams first, then attach repos
A clean setup usually starts with the team structure, not the repo list. That keeps the scope aligned with reporting lines and avoids one repository being counted in multiple places without a clear reason.
- List the teams you want to report on.
- Confirm each team’s ownership boundaries in GitHub.
- Attach the repos that reflect that team’s actual delivery work.
- Check whether any repos should be shared or excluded.
The team-and-repo mapping flow is documented here: /docs/teams-and-repos. If you are still setting up access, review /docs/setup and /docs/how-it-works.
Watch for the three common scope mistakes
Most KPI confusion comes from the same few issues. Catch these early and you avoid hours of chart-chasing later.
1. Mixing platform and product work
If a platform team supports several product teams, a single repo may contain work with very different delivery patterns. In that case, a repo-only view can blur the story.
2. Counting shared repos twice without intent
Shared ownership is normal, but it should be deliberate. If two teams both need the same repo in their scope, make sure the reporting question is still valid for both views.
3. Leaving retired repos in scope
Inactive repositories can skew trends, especially if a team has moved work elsewhere. Review mappings when ownership changes or when a repo becomes low-activity.
When something looks inconsistent, use the guidance in /docs/troubleshooting and check the product limits in /docs/limitations. For pilot-specific constraints, see /docs/limitations#pilot.
Use scoped KPIs to make dashboard views comparable
Once the mapping is in place, the value is consistency. A scoped KPI lets you compare one team to its own history, or compare similarly scoped teams against each other.
On the dashboard, team KPIs, trend charts, and the performance table are most useful when each row or chart reflects a clear owner. That makes it easier to explain changes in review time, throughput, or other delivery metrics without debating what’s included.
For a deeper look at the dashboard layout, see /docs/dashboard and /docs/team-analytics. If you want milestone-style checkpoints for reviews, /docs/chart-milestones is worth a look.
Review the mapping on a regular cadence
Team boundaries and repository ownership change. A mapping that worked at launch can drift as products split, teams merge, or shared services move.
- Review mappings when org ownership changes.
- Check scope before a quarterly planning cycle.
- Confirm the repo list after a major migration or re-org.
- Update the mapping when a team starts owning a new service or component.
If your team uses weekly staff meetings, scoped KPIs are easier to discuss when the view stays stable from week to week. You can pair that with the weekly summary in /docs/weekly-summary and the staff-meeting guidance in /docs/guides/staff-meeting-metrics.
FAQ
Can one repo belong to more than one team?
Yes, if that reflects how the work is actually owned. The important part is being deliberate about it. If a shared repo appears in multiple team views, make sure each view still answers a distinct management question.
Should I map teams by GitHub org teams or by management structure?
Use the structure that best matches how work is delivered. In many cases, GitHub team membership is the most practical starting point, but the metric scope should still reflect actual ownership and reporting needs.
What if the team owns work across several repos?
That is common. Map all relevant repos into the same team scope so the KPI reflects the full delivery surface, not just one codebase.
How do I know the scope is too broad?
If the metric is no longer useful for a team-level decision, the scope is probably too broad. A good rule is that the KPI should help a manager explain recent change in one team’s delivery flow without needing to subtract unrelated work.
What should I check if the numbers do not match expectations?
Start with team and repo scope, then review connected access, repo ownership, and any excluded or inactive repositories. If you need a checklist, use /docs/faq and /docs/troubleshooting.
Ready to map teams and repos for scoped KPIs? Start your setup in /app/onboarding.