If you want GitHub PR data to show up in a delivery dashboard without a long setup project, start with the connection, then map the right teams and repos, and finally verify the first sync. That order keeps the pilot simple and makes the numbers easier to trust.
This guide walks through the practical parts of a GitHub engineering metrics setup: what the read-only app connection does, how daily sync works, what to check before you map scope, and where teams usually get stuck during pilot setup. For the product flow, see how it works and the setup guide.
1) Start with the GitHub connection
The connection step is the foundation. DeliveryCompass uses a read-only GitHub App install and OAuth so it can pull PR delivery data without changing your GitHub workflow. After setup, data syncs daily, which is enough for team-level dashboards and weekly review.
Before you begin, confirm who owns the GitHub organization, who can approve the app install, and which teams should be in the first pilot. If your org prefers to review constraints first, check the limitations page, including pilot-specific notes.
What to have ready
- A GitHub organization admin or equivalent approver
- A short list of pilot teams
- The repos those teams actively use
- A clear owner for validation after the first sync
2) Map teams and repos before you judge the dashboard
Most setup friction comes from scope, not from the connection itself. If teams are mapped too broadly, the dashboard can blur ownership. If the mapping is too narrow, you miss relevant PRs and the metrics stop matching team reality. The goal is simple: map the repos that actually represent the team’s delivery work.
Use the teams and repos guide to define scoped KPIs. That page is worth reading before pilot kickoff because it helps you avoid false starts like mapping shared repos to every team or leaving out a repo that carries most of the work.
A practical mapping checklist
- List the repos that contain the team’s active PR flow
- Exclude repos that are only incidentals or tooling unless they matter to delivery
- Decide how to handle shared repos and cross-functional work
- Review the mapping with a team lead before locking it in
3) Verify the first sync with real GitHub activity
Once the connection and mapping are in place, the first check is whether the dashboard reflects recent PR activity in the right scope. You are not looking for perfection on day one; you are looking for consistency. The dashboard should start showing team KPIs, trend charts, and the team performance table in a way that matches the mapping you chose.
If you want to understand what those views are meant to show, the dashboard page and metrics page are the primary references. If you are comparing teams, the team analytics page explains the chart grid and drill-down flow.
What to confirm in the first pass
- Recent PRs appear in the expected team scope
- Trend charts move in a way that matches recent work
- Team names and repo mapping are readable to managers
- The data shown is enough for a weekly review, not a spreadsheet audit
4) Use the weekly summary to validate the setup in a staff meeting
A good pilot does not end at “the data is there.” It ends when managers can use the data in a meeting without extra interpretation work. The weekly summary is useful here because it adds attention callouts that help you focus on what changed, what needs discussion, and where a team may need follow-up.
For a quick reference on meeting use, see weekly summary and the staff-meeting guide at staff meeting metrics. If you are trying to explain the dashboard to other leaders, the weekly summary is often the easiest place to start.
5) Look for contributor signals, not just aggregate numbers
Once the team-level setup is stable, it helps to look one layer deeper. Contributor coaching signals from GitHub PR metadata can show where review flow is slowing down, where a PR is waiting too long, or where a pattern is repeating across the team. That gives managers something concrete to discuss without turning the dashboard into a scorecard.
engineering intelligence for GitHub PR delivery
For more detail, see profile and the code review responsiveness guide. If you are choosing which metrics to center in the pilot, the choosing delivery metrics page can help keep the scope focused.
6) Troubleshoot the common pilot setup blockers
When a GitHub engineering metrics setup stalls, the issue is usually one of three things: access, scope, or expectations. Access problems show up when the right GitHub approver has not completed the install. Scope problems show up when a team’s repos were mapped too loosely or too narrowly. Expectation problems show up when people think the first dashboard should explain every nuance of delivery.
Use troubleshooting for connection issues and FAQ for common setup questions. If you are bringing this into a broader rollout, the GitHub metrics for managers guide is a good companion read.
When to pause and fix setup instead of pushing ahead
- The wrong teams are showing up in the dashboard
- Key repos are missing from the mapping
- Managers cannot explain what the chart is measuring
- The pilot group is too broad to validate quickly
FAQ
Do I need admin access to connect GitHub?
You need the right GitHub organization approval to install the read-only app and complete OAuth. In practice, that usually means involving an org admin or the person who owns GitHub app installs for your organization.
How long does the first sync take?
Plan for the initial connection and mapping to happen first, then verify the first daily sync. Because sync is daily, you should expect the dashboard to reflect changes on the next sync cycle rather than instantly.
What if my teams share repos?
Shared repos are normal, but they need a clear mapping decision. The safest approach is to agree on ownership rules before the pilot starts so the scoped KPIs match how the teams actually deliver work.
What should I review first if numbers look off?
Start with the mapping, then check whether the right repos are included, and then confirm the dashboard is reading the team scope you intended. If that still does not resolve it, use the troubleshooting guide for the connection flow.
How do I know the pilot is ready to expand?
When the dashboard matches real team activity, managers can use the weekly summary in a meeting, and the scope rules are clear enough that new teams can be added without rework, the pilot is usually ready for the next step.
If you are ready to try the setup in your own org, start the onboarding flow at /app/onboarding.