If your goal is to get useful delivery metrics out of GitHub, start with a clean setup: connect the read-only app, map the right teams and repos, and confirm the first daily sync before you judge the dashboard. That sequence prevents most of the confusion we see in pilots.
Start with the connection, not the charts
The fastest way to stall a rollout is to jump into metrics before the connection is stable. First, install the read-only GitHub App or complete OAuth, then confirm the workspace can access the repositories you want to track. The connection is the foundation for everything else in the docs and in the how it works overview.
For a smooth start:
- Use a dedicated GitHub account or admin-approved flow for setup.
- Check that the selected org and repos match the scope you want to report on.
- Wait for the daily sync to complete before comparing numbers.
Map teams and repos before you define success
Metrics only make sense when they are scoped correctly. If a team’s repos are mixed with unrelated work, the dashboard will show numbers, but they will not be useful for management decisions. Use teams and repos to define the reporting boundaries first.
A practical mapping approach:
- List the teams you want to report on.
- Associate each team with the repos it actually owns.
- Exclude shared or experimental repos unless they are part of the team’s normal delivery work.
- Review the mapping with the engineering lead before you treat it as final.
Confirm the first data pull before you share the dashboard
Once the connection and mapping are in place, verify that the dashboard is showing the expected teams, trends, and table rows. The dashboard gives you the overview KPIs, trend charts, and team performance table, while team analytics helps you drill into the underlying chart grid.
When reviewing the first sync, look for three things:
- Team names match the mapping you expected.
- Repo scope looks right for each team.
- Trend lines and totals are moving in a way that fits the current delivery pattern.
Use the weekly summary to validate the setup in context
A good setup is not just technically correct; it also supports the conversations you plan to have. The weekly summary is useful here because it surfaces attention callouts you can bring into staff meetings. If the summary feels off, it is often a mapping issue rather than a reporting issue.
For a quick validation, ask:
- Do the callouts reflect the teams you intended to include?
- Are any repos missing that should be part of the reporting scope?
- Do the summary trends align with what managers already know about current work?
Read coaching signals after the scope is right
Contributor coaching signals can be helpful, but only when the team and repo scope is accurate. Otherwise, you may end up discussing patterns from the wrong workstream. Use profile details and metrics guidance to understand what the signals represent before you use them in coaching conversations.
This is where engineering intelligence for GitHub PR delivery becomes practical: start with the right scope, then use the signals to coach teams with context, not surveillance. It also helps to keep the pilot narrow at first. If you need guardrails on what the pilot can and cannot prove, review pilot limitations before you expand the rollout.
Common setup issues and how to fix them
Most early setup problems are simple and repeatable. The goal is not to make the process perfect on day one; it is to reduce avoidable friction.
- Wrong repo scope: Recheck the team-to-repo mapping and remove unrelated repositories.
- No data yet: Confirm the daily sync has had time to complete.
- Unexpected team totals: Look for overlapping repo ownership or shared repos included twice.
- Confusion about what the charts mean: Point the team to the choosing delivery metrics guide before comparing numbers.
If you are still stuck, use the troubleshooting guide and the FAQ for setup-specific checks.
FAQ
How long does the first sync take?
After the GitHub connection is approved, the first daily sync may take some time to populate the dashboard. Check again after the sync window has had a chance to complete.
What should I connect first: orgs, teams, or repos?
Start with the GitHub connection, then map the teams and repos that define your reporting scope. That order keeps the setup clean and easier to review.
Why do my numbers not match what another manager expects?
Differences usually come from scope. One team may be seeing a different repo set, or shared work may be included in one report and excluded in another. Review the mapping in teams and repos.
Can I use the dashboard before every team is mapped?
Yes, but treat early results as partial. A narrow pilot can still be useful if everyone understands the current scope and the limits documented in pilot limitations.
Where should I go next after setup?
Once the connection is stable, move to GitHub metrics for managers or PR flow for engineering teams to turn the setup into a working management routine.
Ready to set up your own workspace? Start the onboarding flow at /app/onboarding and use the docs above to keep the connection, scope, and pilot on track.