Table of contents
Connecting GitHub to TeamScore
TeamScore connects to GitHub through a GitHub App installation. Once installed, GitHub delivers activity events directly to TeamScore, allowing TeamScore to represent developer work using metadata only. Setup takes a few minutes and requires GitHub admin privileges.
Step-by-Step Setup Instructions
Step 1 – Start the Connection in TeamScore
- Go to Services in the top navigation
- Find GitHub in the list
- Select Connect GitHub
Only Admins, Executives, or Owners in TeamScore can initiate the GitHub connection. This action redirects you to GitHub to install the TeamScore GitHub App.
Step 2 – Install the TeamScore App in GitHub
On the GitHub side:
- Choose the GitHub organization where you want to install the app.
- Select which repositories TeamScore should receive events from. You may grant:
- Access to specific repositories, or
- Access to all repositories in that organization
TeamScore does not request permission to read source code. GitHub sends TeamScore event notifications only for supported metadata activities.
After installation, GitHub redirects you back to TeamScore.
Step 3 – Map Your Users
GitHub identifies people by GitHub username, not by email.
This differs from systems like HubSpot or Zoom, where email matching is automatic.
After installation:
- Open the Users Tab in the GitHub integration.
- Map each GitHub username to the correct TeamScore user.
This step is essential. If a GitHub user is not mapped, TeamScore cannot attribute commits, pushes, PR activity, or comments to that user.
TeamScore auto-matches users where possible, but manual confirmation produces the most accurate results, especially for contractors or external contributors using unfamiliar GitHub handles.
What Happens Next
Once the GitHub App is installed and users are mapped:
- Push events arrive immediately.
- TeamScore records the push and then fills in the individual commits with their original timestamps.
- Pull request activity (opened, edited, synchronized, closed) appears in near-real time.
- Issue activity (created or commented on) appears in near-real time.
- Code review events (approvals, requested changes, review comments) appear as metadata activities.
Commit messages that include hashtag-style duration values (for example: #1h30m) allow TeamScore to associate a duration with that commit.
No code content, file diffs, or source lines are ever processed.
For an overview of how GitHub data appears in TeamScore, see GitHub Overview.
Troubleshooting
Activity missing for a developer?
Confirm their GitHub username is mapped to their TeamScore profile.
Push appears but individual commits do not?
Ensure that the pushed commits exist in the connected repository and that timestamps were correctly pulled from GitHub’s API.
PR or issue events not appearing?
Verify the repository is included in the GitHub App installation scope.
TeamScore shows no GitHub data at all?
Reinstall the GitHub App or refresh repository permissions in GitHub’s installation settings.