Connecting GitHub to Acticly: App Install or PAT Setup in 5 Minutes
The GitHub App is the fastest path — one click, zero maintenance. But if your org needs a Personal Access Token instead, here's exactly which two scopes to check and why fine-grained tokens are the wrong choice.
The Best Way to Connect: GitHub App
Before we get into tokens — if you have not connected GitHub to Acticly yet, the GitHub App is the recommended path. Install it from your Acticly settings in one click: automatic token rotation, 3x higher API rate limits (15,000 vs 5,000 calls per hour), self-healing webhooks, and zero manual token management. New repositories are discovered automatically. There is nothing to expire, nothing to rotate, nothing to debug.
Go to Settings → Connections → Install GitHub App and you are done.
When You Need a PAT Instead
Some organizations cannot use GitHub Apps — security policies that restrict third-party app installations, GitHub Enterprise Server instances with limited app support, or teams that simply prefer direct token-based access. For those cases, a Personal Access Token works perfectly well. It takes five minutes and two scopes.
This guide covers that setup.
TL;DR — The 30-second version:
- Go to GitHub → Settings → Developer settings → Tokens (classic)
- Select two scopes:
repoandread:user - Set expiration to 90 days (or no expiration if your org policy allows)
- Paste the token into Acticly’s GitHub connection dialog and click Connect
- Do not use a fine-grained token — they have incomplete API coverage and produce unhelpful error messages when something goes wrong
Read on for the full walkthrough and the reasoning behind each decision.
What Acticly Syncs From GitHub
When you connect your GitHub account, Acticly pulls five categories of data through GitHub’s REST API. Understanding what flows through the connection explains why the token needs the permissions it does.
Repositories are discovered through your token’s access. Every repo you can see — public and private — becomes available for tracking. Acticly reads repository metadata, default branches, and language breakdowns to give you a full picture of your codebase composition.
Pull requests are the core of the analytics. Acticly reads every PR across your selected repositories: title, description, diff size (additions and deletions), branch information, and timestamps for creation, review, merge, and close events. This powers cycle time, throughput, and review efficiency metrics — the numbers that tell you how fast your team ships.
Reviews and review comments are pulled per PR. Who reviewed, when they reviewed, whether they approved or requested changes. This feeds into reviewer load distribution and bottleneck detection — surfacing whether two senior engineers are drowning in review requests while the rest of the team sits idle.
Commits are synced per branch and per PR. Acticly reads commit metadata, author information, and diff stats. Commit patterns drive contributor activity analysis and DORA lead time calculations.
Contributor statistics come from GitHub’s stats endpoints — weekly commit counts per contributor and activity patterns by day and hour. These are the building blocks for workload analysis and burnout indicators.
All of this is read-only. Acticly never writes to your repositories, never opens PRs, never posts comments. The token needs broad read access because the analytics span your entire development workflow, but it never needs write access to anything.
Why Classic Tokens, Not Fine-Grained
GitHub introduced fine-grained Personal Access Tokens as a more scoped alternative to classic tokens. In theory, they let you grant precisely the permissions you need. In practice, they are the wrong choice for an integration like Acticly, for three reasons.
The permission model is complex and incomplete. Fine-grained tokens require you to select from dozens of individual permissions across repository-level and account-level categories. You need “Contents” read access for commits, “Pull requests” read access for PRs, “Metadata” read access as a baseline — and some GitHub API endpoints that Acticly depends on, particularly the repository statistics endpoints for contributor activity, have inconsistent behavior with fine-grained tokens. With a classic token, two checkboxes cover everything.
Error messages do not tell you what is wrong. When a classic token lacks a required scope, GitHub’s API response includes an X-OAuth-Scopes header that tells you exactly which scopes are present and an X-Accepted-OAuth-Scopes header showing what is needed. Fine-grained tokens do not include these headers. You get a 403 Forbidden with no indication of which permission is missing. Debugging a connection that partially works — repositories sync but contributor stats do not — becomes a guessing game.
Fine-grained tokens are scoped to specific repositories. You select which repos the token can access at creation time. If your team adds new repositories later, the token cannot see them. You would need to regenerate the token and update it in Acticly. Classic tokens automatically see every repo your GitHub account has access to, which means new repos are included in Acticly’s sync the moment they are created.
The recommendation is straightforward: use a classic Personal Access Token. The setup is simpler, the debugging is easier, and the integration just works.
Creating Your Token: Step by Step
Navigate to GitHub → Settings → Developer settings → Personal access tokens → Tokens (classic), or go directly to github.com/settings/tokens/new.
Click Generate new token and select Generate new token (classic). GitHub may prompt for your password or two-factor authentication confirmation.
Name the token something descriptive — “Acticly” or “Acticly Analytics” works well. This helps you identify it later when reviewing your active tokens.
Expiration is your call. GitHub recommends 90 days, which is a reasonable default. If your organization requires token rotation, set a calendar reminder to regenerate and update the token in Acticly before it expires. If your security policy allows it, “No expiration” avoids the maintenance overhead entirely.
Scopes — this is the critical part. Check exactly two boxes:
repo grants read access to your repositories, including private ones. This single scope covers repository metadata, pull requests, reviews, commits, diff stats, contributor statistics, and language data. GitHub labels it “Full control of private repositories” but Acticly only reads — it never pushes code, creates branches, or modifies any repository content.
read:user grants read access to your GitHub profile. Acticly uses this to verify the token is valid and to resolve contributor identities — mapping commit authors to GitHub accounts so your analytics show real people, not just email addresses.
Leave every other scope unchecked. Acticly does not need write:repo_hook, admin:org, gist, notifications, or any other permission.
Click Generate token, then copy the token immediately — GitHub only shows it once. If you lose it, you will need to generate a new one.
Connecting the Token in Acticly
With your token copied, head to Acticly.
Open Settings → Connections and click Connect GitHub. Paste your token into the “Personal Access Token” field and click Connect.
Acticly tests the token by calling GitHub’s authenticated user endpoint. If the token is valid, the connection is saved and your first repository sync begins automatically. You will start seeing data within minutes.
If you are using GitHub Enterprise Server, the setup is identical — Acticly supports custom GitHub instances out of the box.
If the connection test fails, the most common causes are: a typo in the token (re-copy from GitHub), using a fine-grained token instead of classic, or a token that has already expired.
Setting Up Webhooks for Real-Time Sync
Without webhooks, Acticly discovers changes during periodic syncs. Webhooks make updates near-instant — when a PR is opened, reviewed, or merged, GitHub notifies Acticly within seconds.
In Acticly, go to Settings → Webhooks. Copy the webhook URL and secret shown for your GitHub connection.
In GitHub, navigate to the repository or organization settings:
- Go to Settings → Webhooks → Add webhook
- Payload URL: paste the webhook URL you copied from Acticly
- Content type: select
application/json - Secret: paste the webhook secret from Acticly
- Events: select “Let me select individual events,” then check Pull requests and Pushes
- Click Add webhook
GitHub sends a ping event to verify the connection. If you see a green checkmark, you are set.
For organization-wide coverage, set up the webhook at the organization level rather than per-repository. This way every current and future repo sends events to Acticly automatically — no maintenance required when your team creates new repositories.
Webhooks are optional but recommended. They do not change what data Acticly can access — the PAT handles all data reading. Webhooks simply control how quickly Acticly learns about new activity.
What if you could just ask:
"Which repos had the longest PR review times last month?"
...and get an instant answer, pulled straight from your connected GitHub data.
Two scopes, five minutes, and your GitHub data starts telling a story. If you are curious what your team’s pull request patterns, review bottlenecks, and contributor trends actually look like — the data is already sitting in your repos. It just needs somewhere to go.