Connecting GitHub to WorkSights

WorkSights connects to GitHub through a GitHub App installation. Once installed, GitHub delivers activity events directly to WorkSights, allowing WorkSights 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 WorkSights

1. Go to Services in the top navigation
2. Find GitHub in the list
3. Select Connect GitHub

Only Admins, Executives, or Owners in WorkSights can initiate the GitHub connection. This action redirects you to GitHub to install the WorkSights GitHub App.

Step 2 – Install the WorkSights App in GitHub

On the GitHub side:

1. Choose the GitHub organization where you want to install the app.
2. Select which repositories WorkSights should receive events from. You may grant:
   
   1. Access to specific repositories, or
   2. Access to all repositories in that organization

WorkSights does not request permission to read source code. GitHub sends WorkSights event notifications only for supported metadata activities.

After installation, GitHub redirects you back to WorkSights.

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:

1. Open the Users Tab in the GitHub integration.
2. Map each GitHub username to the correct WorkSights user.

This step is essential. If a GitHub user is not mapped, WorkSights cannot attribute commits, pushes, PR activity, or comments to that user.

WorkSights 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.
• WorkSights 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 WorkSights 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 WorkSights, see GitHub Overview.

Troubleshooting

Activity missing for a developer?

Confirm their GitHub username is mapped to their WorkSights 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.

WorkSights shows no GitHub data at all?

Reinstall the GitHub App or refresh repository permissions in GitHub’s installation settings.