Overview
Pensero connects to your GitHub organization to understand how engineering work actually gets delivered.
We read metadata from Pull Requests and linked issues, not source code. This allows Pensero to reconstruct real units of work, understand collaboration and effort, and surface delivery signals that are consistent across individuals, teams, and leadership.
Setup is handled by an administrator from the Integrations section and takes only a few minutes.
What Pensero Reads from GitHub
Pensero reads metadata only. We never store or inspect your source code.
From each Pull Request, Pensero captures:
PR title and number
State (open, draft, merged, closed)
Description and references
Key timestamps (created, first comment, approval, merge)
Author and reviewers
Source and target branches
Linked tickets or issues
Diff metrics (files changed, lines added or removed, summary only)
This information gives context on what was delivered, how complex it was, and how work flowed through reviews, without exposing code.
Permissions Required
To function correctly, Pensero requests the following GitHub OAuth permissions:
Scope | What it does |
| Read access to repositories (PRs, issues, commits, branches) |
| Read access to GitHub projects |
| Read access to user profile |
| Read access to organization and team information |
Important: Pensero only reads. It never writes.
Even though GitHub's repo scope technically allows write access, Pensero does not use it. GitHub does not offer a more limited scope for reading Pull Request data via OAuth. This is a GitHub platform limitation, not a choice on our side. We request the minimum permissions GitHub allows to do what we need.
These permissions let Pensero understand how your team collaborates and delivers, such as PR review activity, comments, and cycle times. Pensero does not modify your code, repositories, or any GitHub content.
Self-service vs. Enterprise
For self-service onboarding, Pensero uses GitHub OAuth. If you are on the Enterprise tier and prefer a more controlled integration, we also support a GitHub App setup. This gives your team more granular control over which repositories Pensero can access. Talk to your account team if you want to go that route after your initial setup.
What Pensero Derives from GitHub
Using GitHub metadata, Pensero derives workflow signals such as:
Time to First Comment
Time to Approve
Time to Merge
Diff summaries used for code understanding
These signals help you spot review bottlenecks, approval delays, and structural slowdowns, using real delivery data.
How Pensero Organizes Work
GitHub activity is never analyzed in isolation.
Pensero assembles work into structured units:
Items: individual PRs or issues
Chunks: related work from a single contributor
Superchunks: shared delivery packages involving multiple contributors
This structure reflects how work actually happens across people and tools, ensuring delivery insights scale from individuals to teams and the company.
How to Connect GitHub
First-Time Setup
Step 1 - Go to Integrations
From the left sidebar, open Integrations in Pensero.
Step 2 - Complete Giuthub Authentication
Find GitHub in the list and click Connect.
You must be a GitHub Organization Owner to complete the installation.
Step 3 - Grant Permissions
Follow GitHub’s OAuth prompts and grant the required permissions.
Step 4 - Select Repositories
Choose which repositories Pensero should analyze.
You can update this selection anytime from the GitHub integration settings.
How to add new GitHub repositories and verify data ingestion
After GitHub is connected, admins can add more repositories to Pensero at any time. This is useful when a new repository is created, a team starts working in a different repo, or an existing repo was not selected during the first setup.
Step 1 - Go to GitHub integrations
Open the GitHub repositories page in Pensero:
You can also access this from Settings → Integrations → GitHub → Manage.
You need Pensero admin permissions to manage GitHub repositories.
Step 2 - Add repositories
Click Add repositories.
This opens the repository selection page.
Search for the repository you want to connect, select it, and add it to Pensero.
If the repository does not appear, check that:
The GitHub integration is connected
The GitHub account used for the integration has access to the repository
The repository belongs to the connected GitHub organization
GitHub organization permissions or SAML SSO are not blocking access
Step 3 - Review the repository in the integrations page
After the repository is added, return to the GitHub integrations page.
Open the repository from the list and review its status.
You should check:
The repository appears in the connected repository list
The PR workflow is active
Auto-sync is enabled
When Auto-sync is enabled, Pensero fetches data from that repository on a daily basis.
If auto-sync is disabled, Pensero will not continue ingesting new data from that repository automatically.
Step 4 - Check the repository details
Click into the repository detail page to review whether data is being fetched correctly.
From this page, you can review:
PR processing health
PRs by Git user
Merged PRs
Pull requests ingested by Pensero
Pull requests skipped by Pensero
This helps confirm whether Pensero is receiving data from the repository and whether the PRs are being processed as expected.
Step 5 - Review sync logs and skipped PRs
Use the repository detail page and sync logs to understand what Pensero ingested and what was skipped.
A PR may be skipped when Pensero cannot map the GitHub user to an active Pensero user, or when required user identity mapping is missing.
If you see skipped PRs, review user mappings in: Organization → Users
You can also review unlinked users here
Make sure each engineer’s GitHub identity is linked to their Pensero profile. Once the user mapping is fixed, Pensero can correctly attribute future work from that repository.
Troubleshooting
OAuth “Grant Access” stuck with infinite spinner
This typically occurs when SAML SSO is enabled in your GitHub organization.
To resolve:
Ensure you are logged in with an active SAML session.
Visit:
(Replace {yourOrgName} with your actual org name.)
Reattempt installation.
Why Forked Repositories May Not Be Visible
GitHub applies stricter security rules to repositories that are forks of external organizations.
Accessing a forked repo requires your Personal Access Token to be explicitly approved through SAML SSO.
To resolve:
Request access to the original (parent) organization.
Authorize Pensero’s GitHub OAuth token here:
Ask the parent organization owner to approve your request:
Think of the organization’s security policy as a border checkpoint:
Internal Travel (Accessing a regular private repo): When your token accesses a repository that was created inside your organization and has no external parents, it’s like traveling within the country’s borders. The security check is standard, and your token (with the right scopes) is allowed through.
International Travel (Accessing a forked repo): When your token tries to access a fork of an external repository, GitHub sees that this resource has a “foreign” connection to the parent organization. This is like trying to cross an international border. The original organization’s policy flags this action and says, “Wait, for any international travel, we require a special visa.”
In this analogy, the “special visa” is the SAML SSO authorization on your Personal Access Token. The policy is designed to prevent potential data leakage or unauthorized interactions with external entities, so it applies a stricter check on forked repositories.
Instructions for the User Who Added the GitHub Account to Pensero
The original organization’s security policy requires your Personal Access Token to be explicitly authorized via SAML Single Sign-On before it can be used to access repositories that are forked from external organizations.
Request access to the original organization: If your fork (
my_org/repository) has a parent path oforiginal_org/repository, you need to have access to theoriginal_orgorganization. Member access is sufficient.Request grant access for Pensero Git Repos OAuth: Once member access is granted, you need to request grant access for
Pensero Git Repos OAuthon behalf of your OAuth token. To do this, go to https://github.com/settings/connections/applications/Ov23liAtOAfOtnLhJypa. You will see a list of organizations that have access. Click on Grant to request access for theoriginal_org.Organization owner approval: The organization owner of
original_orgmust approve your request at this link:https://github.com/organizations/original_org/settings/oauth_application_policy(replaceoriginal_orgwith the actual parent fork organization name). They will see the request asPensero Git Repos OAuth.
GitHub activity is missing after previously syncing correctly. What should I check?
If PRs or commits stop appearing in Pensero, first check whether the GitHub integration is still connected and syncing.
A common cause is that the GitHub integration was set up by a user who no longer has the right permissions, has left the organization, or whose GitHub access changed.
Check:
The GitHub integration is connected.
The user who originally connected GitHub still has access to the organization and repositories.
The affected repositories are still connected in Pensero.
The sync log does not show permission or authentication errors.
If the integration is failing, reconnect GitHub with a user who has the right GitHub organization permissions.
What happens if an engineer has multiple GitHub profiles?
A single Pensero user can have multiple GitHub identities linked to their profile.
This is useful when GitHub shows the same engineer under different users, emails, or commit authors.
If those identities are not linked, activity may appear as unlinked or be attributed to a different profile.
To fix it:
Go to Org → Settings → Users.
Open the user profile.
Go to Integrations.
Add all GitHub users or emails used by that engineer.
You can also review unlinked users here:
Why can’t Pensero access our GitHub repositories?
This can happen if your GitHub organization has an IP allow list enabled.
You may see this error:
“Although you appear to have the correct authorization credentials, the organization has an IP allow list enabled, and your IP address is not permitted to access this resource.”
Even if the authorization is correct, GitHub may block Pensero if our IPs are not allowlisted.
Please ask for human support through the Pensero in-app chat, and we will provide the right IP address or IP ranges to allowlist.
Once the IPs are allowlisted, make sure the Auto-sync option is enabled in the GitHub integration. Pensero will try to ingest the data within the next hour.