If you want reliable GitHub engineering metrics setup, start with the connection itself: install the GitHub App or connect with OAuth, confirm the right repos are in scope, and verify the first daily sync. Once that is done, the rest of the dashboard becomes much easier to trust and use.
The goal is not just “connected.” It is “connected in a way that matches how your teams work.” That means a clean team-to-repo map, a clear pilot scope, and a quick check that the GitHub PR metadata you plan to review is actually being collected.
Start with the connection method that fits your environment
Most teams begin with a read-only GitHub App install. In some cases, OAuth is used during setup depending on your internal workflow. Either way, the purpose is the same: let the delivery dashboard read GitHub PR metadata without changing anything in GitHub.
Before you connect, make sure you know which GitHub organization, teams, and repositories should be included. If you skip that step, you usually end up cleaning up scope later.
- Confirm the GitHub organization you want to measure.
- Identify the repos that belong in the first rollout.
- Decide whether you are setting up one team or a small pilot group first.
- Review the setup expectations in /docs/setup.
Map teams and repos before you review metrics
Metrics are only useful when they reflect the right team boundaries. That is why team and repo mapping matters so much during setup. If a repo is left out, the team view will look incomplete. If a shared repo is included in the wrong place, the numbers can be misleading.
Use the team-and-repos mapping flow to keep scoped KPIs aligned with your org structure. This is especially helpful when one engineering team owns more than one repo, or when a repo serves multiple teams.
- Map each team to the repos it truly owns.
- Keep the pilot narrow at first if ownership is unclear.
- Revisit the mapping after the first daily sync if anything looks off.
For more detail, see /docs/teams-and-repos.
Check the first sync before you judge the dashboard
After the connection is live, wait for the first daily sync and confirm that the expected PR activity is coming through. Early setup issues usually show up here: missing repos, empty charts, or a team that has less data than expected.
Do not treat the first screen you see as final. The best practice is to verify that the dashboard is populated, then compare the numbers against a known recent PR sample from GitHub.
- Look for visible team KPIs in the overview dashboard.
- Confirm trend charts are populating.
- Check that the team performance table reflects the selected scope.
If something does not match, use /docs/troubleshooting to narrow down whether the issue is connection, permissions, scope, or timing.
Use the pilot to reduce setup friction
A pilot is the safest way to finish GitHub engineering metrics setup. Start with a small set of teams and repos, validate the data, then expand once the scope is right. This avoids long cleanup cycles later and helps managers build confidence in what they are seeing.
Keep the pilot focused on one question: “Does this connection accurately reflect the delivery flow for the team we care about?” If the answer is yes, expand. If not, adjust the map before widening access.
There are also practical limits to what a pilot can tell you right away. Review /docs/limitations#pilot so expectations are clear before you scale.
What to verify in the dashboard after setup
Once the connection is stable, use the dashboard to confirm the setup is working the way you expect. The overview dashboard gives you team KPIs, trend charts, and a team performance table, while the team analytics view adds drill-downs for deeper review.
At this stage, you are checking for signal quality, not trying to solve every process problem. Focus on whether the data is usable for recurring team conversations.
- Overview dashboard: are the team KPIs visible and relevant?
- Trend charts: do they show movement over time?
- Team performance table: does the ranking or comparison match your team structure?
- Team analytics chart grid: can you drill into the areas that matter most?
Explore the relevant docs here: /docs/dashboard, /docs/team-analytics, and /docs/chart-milestones.
Common setup mistakes to avoid
Most connection problems are not technical failures. They are scope mistakes, permission mismatches, or pilot choices that are too broad. A simple checklist prevents most of the back-and-forth.
- Do not connect every repo before confirming the pilot scope.
- Do not assume a missing chart means a broken connection.
- Do not map shared ownership without deciding how the team should be measured.
- Do not expand beyond the pilot until the first daily sync looks correct.
If you want a broader overview of the product flow, /docs/how-it-works is a good companion to the setup guide.
FAQ
How long does GitHub connection setup usually take?
For a focused pilot, setup is usually quickest when the repo list and team mapping are already decided. The actual connection is only one part; the review of scope is what often takes the most time.
Should I connect all teams at once?
Usually not. Start with one team or a small pilot group so you can confirm the mapping and data quality before expanding.
What if a repo is missing from the dashboard?
First check whether the repo was included in the team mapping. If it was not, add it and wait for the next daily sync. If it was included and still does not appear, use the troubleshooting docs to check permissions and setup.
What should I review after the first sync?
Look at the overview dashboard, then verify that the team KPIs and trend charts align with a recent sample of GitHub PR activity. If the scope looks right, you are ready to move from pilot to broader use.
Where should I start if I am new to the product?
Begin with /docs and /docs/faq, then move to setup and team mapping so the connection reflects your actual delivery structure.
If you are ready to start a clean pilot, begin here: /app/onboarding.