Table of contents
GitHub Setup
WorkSights connects to GitHub through a GitHub App installation with read-only permissions. Once installed, GitHub delivers activity events to WorkSights for the repositories you grant.
For an overview of how GitHub activity appears in WorkSights, see GitHub IntegrationOverview.
Connecting GitHub
Step 1: Start the Connection
- Go to Services in the top navigation
- Find GitHub in the list
- Click Connect GitHub
Only Admins, Executives, and Owners in WorkSights can initiate the GitHub connection.
Step 2: Install the WorkSights App in GitHub
You will be redirected to GitHub's App installation screen. The installer must be a GitHub organization owner or admin. Members can initiate installs if the organization allows it, pending approval. Personal accounts also work, though member import is skipped for them.
Choose All repositories or Only select repositories. Activity only flows for granted repositories. You can adjust the repository grant later from GitHub's own settings.
The App's permissions are read-only. WorkSights cannot modify anything in your GitHub organization.
Step 3: User Mapping
GitHub identifies people by GitHub username, not by email.
After installation you land on the Users tab. This is the critical step.
GitHub identifies people by username and keeps member emails private, so automatic matching by email is best-effort and most mappings need to be done manually. Map each GitHub username to the correct WorkSights user. Pay particular attention to contractors and external contributors who may use unfamiliar handles.
Unmapped users generate no activity, and events that arrive before mapping are not replayed. Up to 500 organization members are imported at install time, with a daily re-sync after that.
What Happens Next
Once installed and users are mapped, activity begins appearing within roughly 20 minutes of commits, pull requests, and comments happening in the granted repositories. Historical activity is not backfilled.
Developers can add #time tags to commit messages, for example "#time 1h 30m," to set explicit durations on their commit activity. Without a tag, Code activities use a 10-minute default.
Repository grants are managed from GitHub's Settings → GitHub Apps page. User mappings can be reviewed and updated at any time from the integration page.