If your goal is to start a pilot without turning setup into a project, keep it simple: install the GitHub App, connect the right organization, map the teams and repos you want to measure, and confirm the first sync. That is usually enough to get a useful pilot moving in minutes, not days.
This guide walks through the practical setup path for a GitHub App engineering pilot setup, with the few checks that matter most before you invite your team to look at the dashboard.
engineering intelligence for GitHub PR delivery
What a fast pilot setup should accomplish
A good pilot does not try to measure everything on day one. It should answer a small set of delivery questions for a specific team or two. In practice, that means:
- connecting one GitHub organization safely with a read-only install,
- mapping a focused set of teams and repos,
- letting daily sync populate the first dashboard views, and
- reviewing whether the data matches how your team actually works.
If you want a broader view of what the product shows after setup, start with the dashboard and team analytics.
Step 1: Install the GitHub App
Start with the GitHub App installation for the organization you want to include in the pilot. The install is read-only, so it is designed for measurement rather than workflow change. That keeps the pilot low risk and easier to approve.
During install, make sure you connect the organization that owns the repos you want to include. If your engineering group spans multiple orgs, pick one scope for the pilot and expand later if needed. For the setup flow itself, see /docs/setup.
Step 2: Confirm the pilot scope before mapping
Before you map anything, decide which teams should be in the pilot and which repos belong to each team. This is the point where most setup friction shows up: too much scope creates confusion, and too little scope makes the first charts unhelpful.
A good pilot scope is narrow enough to be recognizable in a staff meeting and broad enough to show a real pattern. If you are choosing what to include, the guidance in teams and repos and choosing delivery metrics can help you keep the setup grounded.
Step 3: Map teams and repos carefully
Once the organization is connected, map the teams and repositories that belong together. Scoped mapping is what makes the KPIs useful for managers, because it keeps team-level views from being distorted by unrelated work.
When in doubt, prefer a smaller, cleaner mapping over a broad one. You can always expand the pilot after the first review. If the mapping does not look right, check the references in /docs/teams-and-repos and /docs/troubleshooting.
Step 4: Let the first daily sync run
After install and mapping, give the system time to sync. Daily sync is what fills in the initial dashboard, trend views, and team performance table. For most pilots, the first useful readout comes after the initial sync completes and the mapped repositories have data to summarize.
At this stage, avoid overchecking every number. The better question is whether the team-level shape looks plausible. If the trend lines or table rows seem off, review the pilot scope and confirm the mapping before assuming the data is wrong.
Step 5: Review the first views with the team
The fastest pilots are usually the ones that end with a short review, not a long implementation meeting. Start with the overview dashboard, then move into one or two charts that matter to your team. If you need a structured way to interpret the first views, use the product tour and the notes in chart milestones.
For managers, the most useful question is simple: do these views help us talk about delivery with less guesswork? If the answer is yes, you have a workable pilot.
Common setup friction and how to avoid it
Most pilot delays come from a small number of issues:
- the wrong GitHub organization is connected,
- team-to-repo mapping is too broad or incomplete,
- the pilot is expected to cover every team at once, or
- the first sync has not completed yet.
If you hit one of these, slow the scope down before you troubleshoot the charts. The limitations page also helps set expectations for what is and is not available during a pilot: /docs/limitations#pilot.
FAQ
How long does a GitHub App engineering pilot setup take?
For a focused pilot, the connection and initial mapping can be done quickly. The remaining time is usually spent confirming scope and waiting for the first sync to populate the views you want to review.
What should I map first?
Start with the team or teams you want to discuss in your next staff meeting, then map the repos that clearly belong to those teams. Small, clear scopes are easier to validate than broad ones.
Do I need to connect every repository in the organization?
No. For a pilot, it is usually better to connect only the repos that support the team or workflow you want to study. That keeps the first dashboard readable and easier to trust.
What if the data does not match my team structure?
Review the team and repo mapping first. If the scope is correct but the view still looks off, use /docs/troubleshooting and compare your setup against /docs/faq.
Where should I go after the pilot is connected?
Move from setup to interpretation: review the dashboard, look at team analytics, and decide whether the scope is ready for a wider rollout. The overview in /docs is a good place to continue.
If you are ready to start, begin the pilot at /app/onboarding.