Troubleshooting GitHub Data Quality

This guide helps you self-diagnose and fix the most common GitHub data quality issues in Span — for example, when a person who you know is shipping code shows a - (no data) in PRs merged / week, or when their PRs appear but their PR Lifecycle and commit-based metrics are missing.

You can work through it on your own; in most cases the root cause is a small configuration mismatch that you can correct from within Span or your GitHub organization.

Table of contents

1. How Span connects GitHub data to a person

1. Before you start: a 60-second checklist

2. Quick diagnosis flowchart

3. Issue 1 — I see a in "PRs merged / week"

4. Issue 2 — I see PRs merged, but no PR Lifecycle or commit metrics

5. Other common causes of missing or partial data

6. How to check and fix a person's local Git email

7. Glossary

8. Still stuck? What to send support

How Span connects GitHub data to a person

Understanding the data flow makes troubleshooting much faster. Span needs three things to line up before a person's GitHub activity appears in their metrics:

1. The repository is connected and synced. Span can only see activity in repositories that your GitHub App installation has access to and that Span has finished syncing. Activity in a repo Span can't see is invisible — even if the person contributed heavily.

2. The pull request is attributed to a person via their GitHub username. Every PR on GitHub has an author identified by a GitHub username (login). Span maps that username to a person in your org. If the username on the PR isn't mapped to anyone (or is mapped to the wrong person), the PR can't be counted for them.

3. The underlying commits are attributed to a person via their Git author email. Commit-level signals — first commit time, coding time, and therefore most PR Lifecycle stages — are matched using the email address recorded in each commit (the user.email set in the contributor's local Git client). If that email doesn't match an email Span knows for the person, the commits stay unattributed even when the PR itself is correctly attributed.

Key takeaway: "PRs merged" depends mostly on (1) repo sync and (2) GitHub username. "PR Lifecycle / commits" additionally depends on (3) the Git author email. This is why a person can have a healthy "PRs merged" count but blank lifecycle metrics.

Before you start: a 60-second checklist

Run through these quick questions before diving into the detailed steps. They resolve the majority of cases.

• [ ] Is the date range wide enough? The metric only counts activity inside the selected time window. Widen it to confirm whether data exists at all.

• [ ] Does the person have a GitHub username set in Span? (See Issue 1.)

• [ ] Is the GitHub username the correct one for this person?

• [ ] Did the person actually merge a PR in the period you're looking at? Confirm directly in GitHub.

• [ ] Was the repository they contributed to connected and synced to Span?

• [ ] Is the person marked as active and as an employee in Span? Inactive or non-employee records may be excluded from some views.

• [ ] Is enough time allowed for sync? Very recent activity (last few hours to a day) may not have synced yet.

If any box is unchecked, jump to the matching section below.

Quick diagnosis flowchart

Use the symptom you're seeing to find the right section:

Issue 1 — I see a in "PRs merged / week"

A - means Span has no PRs attributed to this person in the selected range. If you expect this person to have merged PRs, work through these steps in order.

Step 1 — Confirm the person has a GitHub username in Span

1. Open the person's page in Span (search for them by name).

2. Look for their GitHub username in their profile/integration details.

3. If there is no GitHub username, that's the cause — Span can't match any PRs without it. Add the correct username (see Step 2 for how to find it), or ask an admin to add it. Mappings are managed in the member/people settings under the GitHub integration.

Span cannot match PRs to a person if it doesn't have the right GitHub username for them.

Step 2 — Confirm the GitHub username is the correct one

A username can be present but wrong (typos, an old handle, or someone else's handle). To verify:

1. In GitHub, find a pull request you know this person opened and merged.

2. Note the author handle shown on that PR (the @username next to "opened this pull request").

3. Compare it to the username stored in Span. They must match exactly (GitHub usernames are case-insensitive, but spelling must be identical — no leading @, no extra spaces).

4. If they differ, update the username in Span to the correct one.

Step 3 — Confirm the person actually merged a PR in the period

1. In GitHub, search the org for PRs by this author. A useful search is:

   is:pr is:merged author:THEIR_GITHUB_USERNAME
   

2. Confirm at least one PR was merged (not just opened or closed) and note its merge date.

3. If there are no merged PRs in GitHub for the window you care about, then a is correct — there's simply nothing to show.

Step 4 — Widen the date range in Span

The "PRs merged / week" metric only includes PRs merged inside the selected date range.

1. Expand the date range so it comfortably covers the merge dates you found in Step 3 (when in doubt, widen to the last 90 days or more).

2. Re-check the metric. If data now appears, the original range simply didn't overlap with their contributions.

Step 5 — Confirm the repository is connected and synced

If the username is correct and the person recently merged PRs but you still see -, Span may not have synced the repository they contributed to.

1. Go to the Catalog.

2. Open the Repositories tab.

3. Search for the repository the merged PR (from Step 3) lives in.

   • If the list is long, export it to CSV and search the file.

4. Determine the repository's status:

   • Not in the list → the repo isn't connected to Span. Connect it by granting your GitHub App installation access to that repository (see other common causes), then allow time for the initial sync.

   • In the list but recently added → it may still be syncing. Allow time and re-check.

Step 6 — Re-check after sync completes

After fixing a username or connecting a repository, data is not instantaneous. Allow time for the next sync to run, then revisit the person's page and metrics.

Issue 2 — I see PRs merged, but no PR Lifecycle or commit metrics

If "PRs merged / week" looks correct but PR Lifecycle metrics (Coding, Awaiting First Review, Reworking, Idling, Deploying / cycle time) or other commit-based metrics are blank or only partially populated, the most common cause is a mismatched Git author email on the person's commits.

Why this happens

• PRs are attributed by GitHub username — which is usually configured correctly, so PRs show up.

• Commit-level events (especially First Commit, which anchors coding time and the start of the PR lifecycle) are attributed by the email address baked into each commit by the contributor's local Git client (git config user.email).

• If a developer's local Git email is not one of the emails verified on their GitHub account (and known to Span), their commits can't be tied back to them — so lifecycle and commit metrics stay empty while PR-level counts remain intact.

Typical triggers:

• A personal email configured locally instead of their work email.

• A default/auto-generated email like you@example.com or the machine hostname.

• A new laptop or fresh Git install where user.email was never set.

• The email is set but not added/verified on their GitHub account.

Step 1 — Confirm the symptom

1. Open the person's page in Span.

2. Verify that PRs merged has values but PR Lifecycle / commit metrics are missing or noticeably incomplete for the same period.

Step 2 — Inspect the commit author email

Ask the engineer to run the following in any repository on their machine and share the output:

git config user.email

For a specific commit (e.g. one that belongs to a merged PR with missing lifecycle data), they can confirm the email actually recorded on that commit:

git show -s --format='%an <%ae>' <commit-sha>

%ae is the author email — this is the value Span matches on.

Step 3 — Compare against their GitHub emails

1. Have the engineer open GitHub → Settings → Emails and list the email addresses associated with (and verified on) their GitHub account.

2. Compare the Git author email from Step 2 to that list.

3. If the commit email is not one of their GitHub emails, that's the cause.

Tip: If the engineer uses GitHub's "Keep my email address private" feature, their commits may use a …@users.noreply.github.com address. That's fine as long as the same address is used consistently and is recognized as theirs.

Step 4 — Fix the local Git email

See How to check and fix a person's local Git email for the exact commands. In short: set git config user.email to an email that is verified on their GitHub account.

Step 5 — Understand what gets fixed (and what doesn't)

• New commits made after the fix will be attributed correctly going forward.

• Existing/historical commits keep the old author email — they were written into Git history at commit time. Rewriting history is generally not recommended for shared branches. Going forward, the data will be correct, and trends will recover as new work lands.

Other common causes of missing or partial data

Beyond the two primary issues, these scenarios also produce gaps:

Repository not connected or GitHub App lacks access

Span only sees repos your GitHub App installation can access. If an entire repo or team is missing:

• Confirm the repository appears in Catalog → Repositories.

• Ensure your GitHub App installation includes that repository (org admins can adjust which repos the installation can access in GitHub's organization settings).

• Newly granted repos require an initial sync before data appears.

Multiple GitHub usernames for one person

Some engineers contribute under more than one handle (e.g. a personal and a work account). If only one is mapped, the other account's PRs won't be attributed. Ensure all of the person's GitHub usernames are mapped to their record.

Bot, service, or automation accounts

Bots (e.g. dependabot, release bots, CI accounts) open and merge PRs but aren't people. If a bot is mapped to a person, it can inflate that person's numbers; if it isn't filtered, it may appear as an unexpected contributor. Bot accounts should not be mapped to human person records.

External contributors and forks

PRs from outside collaborators or from forks may not be attributable if the author isn't a member of your org / isn't mapped in Span.

Squash merges and commit attribution

If your org squashes commits on merge, the resulting single commit's author email is what Span sees for that work. Make sure the relevant email is recognized (this ties back to Issue 2).

Sync timing and recency

Data syncs on a schedule. Activity from the last few hours — or right after you fix a username/email or connect a repo — may not appear until the next sync completes. Give it time before concluding something is broken.

Person not active / not an employee

Some views filter to active employees. If a person is marked inactive, terminated, or non-employee, they may be excluded. Verify their status on their Span profile.

How to check and fix a person's local Git email

These commands are run by the engineer on their own machine.

1. Check the current email Git will use for new commits:

git config user.email

2. Check the username too (optional, for completeness):

git config user.name

3. Set the correct email — one that is verified on their GitHub account.

Globally (applies to all repos on the machine):

git config --global user.email "work-email@yourcompany.com"
git config --global user.name "Their Name"

Or only for a single repository (run inside that repo, useful if they juggle personal and work accounts):

git config user.email "work-email@yourcompany.com"

4. Verify the email is verified on GitHub: GitHub → Settings → Emails. The address above should be listed and verified. If it isn't, add and verify it there.

5. Verify a future commit will carry the right email:

git config user.email   # should now print the corrected address

From here, new commits will be attributed correctly. Lifecycle and commit metrics will recover as new work is committed and synced.

Note on history: Past commits retain the email they were authored with. Avoid rewriting shared Git history just to backfill metrics — fix the config so everything from now on is correct.

Glossary

• PRs merged / week — Count of pull requests merged in the selected period, attributed to a person via their GitHub username.

• PR Lifecycle — The stages a pull request moves through: Coding (First Commit → PR Opened), Awaiting First Review (PR Opened → First Review), Reworking (First Review → Last Action), Idling (Last Action → Merge), and Deploying (Merge → In Production). Early stages depend on commit data and therefore on the Git author email.

• GitHub username (login) — The @handle that identifies a PR's author on GitHub; how Span attributes PRs to a person.

• Git author email — The user.email recorded in each commit; how Span attributes commits (and commit-derived lifecycle stages) to a person.

• Catalog → Repositories — Where you can see which repositories Span has connected and synced, with a CSV export for searching large lists.

• Sync — The scheduled process that pulls GitHub data into Span. New activity and configuration fixes take effect after the next sync.

Still stuck? What to send support

If you've worked through the relevant sections and data is still missing, contact support with as much of the following as possible — it lets us resolve issues much faster:

• The person's name and a link to their page in Span.

• The metric affected (e.g. "PRs merged / week" vs "PR Lifecycle / cycle time") and the exact date range you're viewing.

• The GitHub username stored in Span for that person.

• A link to a specific GitHub PR you expect to see (ideally a merged one), including its merge date.

• For lifecycle/commit issues: the output of git config user.email and git show -s --format='%an <%ae>' <commit-sha> for an affected commit, plus the list of emails verified on the person's GitHub account.

• The repository name, and whether it appears in Catalog → Repositories.

• Roughly when the activity happened and when you first noticed the gap.