> For the complete documentation index, see [llms.txt](https://docs.revenium.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.revenium.io/track-and-control-costs/analyze-ai-tooling-spend/github-integration.md).

# GitHub Integration

Connect your GitHub organization to surface PR attribution and productivity metrics alongside AI coding assistant usage in Revenium.

Connecting GitHub to Revenium adds shipped pull request data to the AI Assistants dashboards. Without GitHub, the dashboards measure AI assistant activity: sessions, tokens, cost. With it, you can cross-reference that spend against what developers actually deliver, surfacing per-developer productivity metrics and attributing pull requests to AI-assisted work.

## What connecting GitHub adds

Once connected, the **Value by User** tables for Cursor, Codex CLI, and Gemini CLI can show four pull request columns. Two are named for the assistant, such as **PRs with Cursor** and **Cursor Adoption**. The Claude Code **People** roster instead shows **PRs merged** and **Cost / PR**.

| Column                    | Description                                                                                                                       |
| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| **PRs Merged**            | Total pull requests merged by this developer in the selected period, regardless of how they were authored                         |
| **PRs with \[Assistant]** | PRs where that assistant left its attribution — on a commit or in the pull request description — matching its detection signature |
| **Cost/PR**               | This developer's API-equivalent estimated value divided by PRs merged — the cost side of a basic productivity ratio               |
| **\[Assistant] Adoption** | The share of this developer's merged PRs attributed to that assistant                                                             |

These columns let you ask: are high-spend developers also shipping the most? Which developers are getting the most delivered per dollar of AI spend? Is AI adoption actually showing up as more code delivery?

{% hint style="info" %}
**The assistant-attributed columns can significantly undercount AI-assisted work — they never overcount.** A PR only counts toward an assistant when a matching signature for that specific assistant appears on one of its commits or in the pull request description — see [AI co-author detection patterns](#ai-co-author-detection-patterns) below. A miss happens when the AI-assisted work is both committed and opened by hand, or when that assistant's attribution is disabled. Either way, the PR is left unattributed even though AI was involved. The true AI-assisted share is usually higher than what these columns show.
{% endhint %}

The same attribution also feeds a vendor-level **Cost/PR** column on **Intelligence > Providers > Comparison**. [PR Health](https://docs.revenium.io/track-and-control-costs/analyze-ai-tooling-spend/pr-health.md#vendors-what-does-a-merged-pull-request-cost-with-each-one) explains how that column counts pull requests.

## Which tools support PR data

The Cursor, Codex CLI, and Gemini CLI **Value by User** tables can show merged pull requests, pull requests attributed to that assistant, cost per pull request, and adoption rate. The Claude Code **People** roster shows merged pull requests and cost per pull request. Detection is per-assistant: each assistant is matched against its own signature (see [AI co-author detection patterns](#ai-co-author-detection-patterns) below), so a commit or pull request only counts toward the assistant whose signature it actually carries, not toward every tab at once.

If an assistant leaves no mark Revenium can match on, its figure reads **Not detected** instead of a zero. That means unmeasured, not that the assistant helped with nothing. Columns appear only for assistants with attributed counts, so a tab never fills with empty cells.

### Merged pull requests by repository

Open a person's details from **Intelligence > AI Assistants > Claude Code** to see **Where their PRs land**, or from **AI by Employee** to see **PRs merged by repository**. The table groups that person's merged pull requests by repository for the selected time range and can open the matching pull requests on GitHub.

The repository breakdown covers GitHub only. If GitLab is also connected, its merge requests can contribute to the person's overall merged-PR figure, but they do not create per-repository rows in this table.

## Prerequisites

These prerequisites apply to the personal access token connection below. For the GitHub App, see [Before you start](#before-you-start).

* A GitHub **fine-grained** personal access token with these read-only permissions:
  * **Repository permissions:** Pull requests, Metadata (auto-selected by GitHub)
  * **Organization permissions:** Members
* Developer identities that Revenium can map to your organization's GitHub accounts, using organization identity information, commit emails, or a mapping you set by hand

The connect screen provides a link that pre-selects these permissions for you. If your organization requires administrator approval for fine-grained tokens, the token remains pending until an owner approves it, and until then it sees only the organization's public data. Revenium still connects the token and shows a warning that it can see no private repository in the organization, so you can ask an organization owner to approve it. The connection is not marked invalid for this reason alone.

### Your token's GitHub limit

GitHub gives each person 5,000 API calls an hour, shared by every token they own and every app acting for them, so a token made just for Revenium still draws on its owner's limit. Revenium's sync uses that token. A new connection, or a change to its repositories or AI co-author detection patterns, loads up to 90 days of pull requests in hourly passes until it has read them all. Each pass can use up to 90% of the limit, and for a large organization the load takes several hours. During that time, the token owner's other tools and scripts may hit GitHub rate limits. Once the load completes, the connection reads once a day, which uses little of the limit. The connect screen says the same before you save.

To keep the sync off anyone's account, connect with the [Revenium GitHub App](#connect-with-the-revenium-github-app) instead: it uses the app installation's own limit, not a person's.

{% hint style="info" %}
Classic personal access tokens are also accepted, using the `repo` and `read:org` scopes. Those scopes are considerably broader than Revenium needs, since `repo` grants write access to all repository content, and an organization's approval policy applies only to fine-grained tokens, not classic ones. We recommend a fine-grained token wherever possible.
{% endhint %}

## Connect with the Revenium GitHub App

The Revenium GitHub App connects an organization without a personal access token. It uses the app's own GitHub rate limit, not a person's token, which suits organizations with many repositories: the first load of up to 90 days of pull requests runs in hourly passes within that limit and never slows down a person's other tools. The token connection described below remains available. If your organization is already connected by token, see [Move from a personal access token to the GitHub App](#move-from-a-personal-access-token-to-the-github-app).

### Before you start

You need to be an admin of the selected team in Revenium. Anyone else sees **Ask an admin to install the GitHub App.** on the card. On GitHub, installing the app or approving a request to install it takes an owner of the organization. Linking an installation that is already on GitHub takes an admin of the Revenium team who is a member of the GitHub organization. Check the selected Revenium team before starting. A team connects one GitHub organization through the app. The app must be installed on a GitHub organization, not on a personal account.

### Install the app

1. In Revenium, open **Integrations**, select the **Integrations** tab, and find the **GitHub App** card. Select **Install GitHub App**.
2. On GitHub, choose your organization, pick all repositories or only the ones you want the app to read, review the requested permissions, and confirm the installation.
3. GitHub sends you back to Revenium. The setup page shows **Connecting the GitHub App** while it checks the installation with GitHub. When it shows **GitHub App connected**, select **Back to Integrations**. The first load starts shortly: it reads up to 90 days of pull requests in hourly passes, which can take hours for a large organization, and the card shows **Still loading pull requests** with when the next pass is due until it completes.

If the setup page shows **Approval requested**, a GitHub organization owner must approve the request on GitHub. Select **Confirm with GitHub** on that page so GitHub confirms the request was yours. The page then shows **Request confirmed**. After an owner approves on GitHub, the owner returns to a Revenium page that asks whether to connect the organization to your team, with **Connect to** your team and **Do not connect** buttons. Nothing is connected until the owner chooses **Connect to** your team. If the app is approved but not connected, an admin of the Revenium team who is a member of the GitHub organization finishes it with **Link existing installation**.

If an owner installs or changes the app on GitHub without starting from Revenium, the setup page shows **GitHub App installed** or **GitHub App updated**. An admin of the team who is a member of the GitHub organization selects **Link it to this team**, and GitHub confirms the membership.

### Link an app already installed on GitHub

If the app is installed on GitHub but not connected in Revenium, select **Link existing installation** on the **GitHub App** card. An admin of the Revenium team who is a member of the GitHub organization can link it without installing again. You do not need to be an owner. GitHub asks you to confirm who you are. If the app is installed on more than one organization you belong to, the setup page shows **Pick the organization to link**. Select the button that names the organization you want. Revenium then starts the first sync.

### When an owner is asked to connect a team

When an organization owner installs the app on GitHub after a Revenium team asked for it, and that team's request is the only open request for the organization, GitHub returns the owner to a Revenium page that asks whether to connect the organization to that Revenium team, and names who asked. Select **Connect to** followed by the team's name to give that team the organization's pull request data, or select **Do not connect**. Nothing is connected until the owner chooses. After **Do not connect**, the app stays installed on the organization, and an admin of the Revenium team who is a member of the GitHub organization can connect it later from Integrations with **Link existing installation**. The same applies when the owner is not asked, for example when no request is open or more than one team asked. If the page says **This confirmation expired or was already used.**, check the **GitHub App** card on **Integrations**. If the app is not shown as connected, connect it with **Link existing installation**. If it says **Revenium could not record your choice, so nothing was changed.**, choose again.

### Move from a personal access token to the GitHub App

If your team already connects a GitHub organization with a personal access token, install or link the GitHub App on that same organization. You do not need to disconnect the token connection first. The existing connection becomes the GitHub App connection. It keeps its sync history, allowed repositories, detection patterns and user mappings, and Revenium removes the stored token.

A team connects one GitHub organization through the app, and the app must be installed on an organization, not a personal GitHub account. The reverse move is refused: connecting a token for an organization already connected through the app shows "This organization is connected through the Revenium GitHub App. Disconnect it there before connecting it with a token."

### What Revenium reads

The app requests only these read-only permissions. No write access is needed.

* **Repository permissions**: Pull requests (read-only), Metadata (read-only, auto-selected)
* **Organization permissions**: Members (read-only)

The **GitHub App** card lists the same permissions under **Permissions the app requests** before you install. Revenium stores no personal access token for an app connection.

{% hint style="info" %}
Choose the repositories on GitHub's installation screen. In Revenium, **Settings** on the card can narrow which of those repositories are scanned. Leave the list empty to include all repos the app can access.
{% endhint %}

### Once the app is connected

The **GitHub App** card shows **Organization**, **Last successful sync**, **Last validated**, **Allowed repos** and **AI co-author patterns**. With no repositories selected, **Allowed repos** reads **All repos the app can access**. **Sync now** refreshes the data straight away. **Settings** narrows the repositories or changes the detection patterns. **View Sync Logs**, at the top of the Integrations tab, shows each run. **GitHub PRs by Team Member** shows merged pull requests and identity mappings. Members who are not admins see **Only an admin can change or disconnect this connection.**

**Disconnect** stops syncing the organization. Existing historical data is kept, and the app can be installed again at any time. If an organization owner linked the app, Disconnect also uninstalls it from GitHub, so the app keeps no access. If GitHub has not confirmed the removal, Revenium keeps trying for up to a day, and an organization owner can remove the app there. If a team admin who is only a member of the organization linked the app, Disconnect leaves it installed on GitHub, and an organization owner removes it in the GitHub settings.

PR Health uses the same GitHub data. If the app is uninstalled or suspended on GitHub, or the connection is failing, PR Health shows **GitHub is no longer connected** and its figures stop at the last successful sync. Admins see **Fix it in Integrations**, which opens the GitHub App section.

### Troubleshooting the GitHub App

* The setup page shows **Approval requested**. Select **Confirm with GitHub**, then a GitHub organization owner approves the request on GitHub and chooses **Connect to** your team on the page Revenium shows afterward. If it is approved but not connected, an admin of the team who is a member of the GitHub organization selects **Link existing installation**.
* You returned from GitHub but the card still shows the old state. Refresh the page. If GitHub shows the app as installed but Revenium does not show it connected, select **Link existing installation**.
* The setup page shows **Cancelled on GitHub**. Nothing was connected. Start again from **Install GitHub App**. If the app was installed anyway, use **Link existing installation** instead.
* The setup page shows **The GitHub App could not be connected**. Read the reason it gives. To try again, open Integrations in the team where you started the installation. If the app is already installed on GitHub, select **Link existing installation**; otherwise select **Install GitHub App**.
* The reason says GitHub shows no installation you can link. Confirm the Revenium GitHub App is installed on the organization and that you are a member of it. If an owner still has to approve the request, select **Link existing installation** once they do. An installation already connected elsewhere in Revenium cannot be linked here.
* The reason says the installation has not granted read access to a permission. Accept the app's requested permissions on GitHub, then select **Link existing installation**.
* The setup page shows **Nothing to finish**. That page only finishes a connection started from Integrations. Open **Integrations** to see your connections.
* The Integrations page says Revenium could not finish connecting the GitHub App. Nothing was connected. If the app is already installed on GitHub, an admin of the team who is a member of the GitHub organization selects **Link existing installation**.
* The card says the app is no longer installed on the organization. An admin selects **Install again** on the card to resume syncing.
* The card says the installation is suspended. An organization owner unsuspends it in GitHub, then an admin selects **Sync now**.

## Setting up the integration

Open **Integrations**, select the **Integrations** tab, then **Connect GitHub**. The [Slack](https://docs.revenium.io/integrations/slack.md) and GitLab integrations are on the same tab. Connect with a GitHub personal access token carrying the permissions listed in [Prerequisites](#prerequisites) above. The connection screen shows the last successful validation timestamp and offers a **Sync now** action; data refreshes on its natural cadence otherwise. Either integration on the tab can be reconfigured or disconnected without affecting the other.

In **GitHub organization**, paste your organization's GitHub URL, for example `https://github.com/acme-corp`. A link to any repository in the organization works too. Revenium takes the organization's short name from it and shows **We'll use** with the name it found; check that it is your organization before you continue. You can also type the short name or an `@handle`. The pre-filled token button stays disabled until the organization is filled in, since the link needs it to target the right **Resource owner** on GitHub.

When you generate the token, check that GitHub's **Resource owner** picker shows your organization — the button pre-selects it, but GitHub sometimes asks you to confirm it again. If you see an **Account** tab instead of **Organizations**, the token belongs to your personal account: switch Resource owner to your organization, then re-check the **Pull requests** and **Members** permissions, since switching resets them.

If your organization uses SAML single sign-on, GitHub authorizes a fine-grained token for the organization as you create it. You need a linked single sign-on identity on GitHub first.

The token expires on the date you choose when you create it, and GitHub suggests 30 days by default. Choose an expiry that fits your policy and set a reminder. When the token lapses, create a new one and select **Reconnect** on the GitHub card to enter it.

### Connecting multiple organizations

You can connect more than one GitHub organization to a single Revenium account. Add each organization from the GitHub connect modal; each connection carries its own credential, and PR attribution is drawn from every connected organization. This suits teams whose code is split across separate GitHub organizations rather than concentrated in one.

### Choosing repositories with the repo picker

When you connect an organization, the connect modal offers a **repository picker** so you can select which repositories to track instead of scanning everything. Changing the organization clears the loaded list; select **Load repositories from GitHub** to load the new organization's repositories.

## Once GitHub is connected

The GitHub card on the **Integrations** tab shows the organization, **Last successful sync**, **Last validated** (when the token was last checked), the allowed repositories and the AI co-author patterns. The card re-reads its state every few minutes while the page is open. A new connection, or a change to its repositories or AI co-author patterns, first loads up to 90 days of pull requests in hourly passes; while that runs, the card shows **Still loading pull requests** and when the next pass is due, and **Sync now** answers that a scheduled sync is already running. Once the load completes, the connection reads once a day, around 03:00 UTC, and **Sync now** refreshes the data straight away. A pass that ran out of time before finishing shows as **Last completed sync … ran out of time before finishing**; the next pass resumes from where it stopped. **Settings** changes repositories and detection patterns, **Reconnect** takes a new token, and **Disconnect** removes the connection. **Add another GitHub organization** connects a second organization.

**View Sync Logs**, at the top of the Integrations tab, lists every scheduled and manual GitHub and GitLab sync. Select **Failures** to show only failed runs, then open a run for the provider's message and the suggested next step.

### Member matching is limited

If the GitHub card shows **Member matching is limited**, GitHub is not letting the token read your organization's full member list. The connection stays connected, and pull request sync and the other matching sources continue, but matching people through their public GitHub profiles is limited. To restore it, an admin updates the token on GitHub and reconnects it in Revenium:

* A fine-grained token needs your organization as **Resource owner** and **Organization permissions** > **Members**: Read-only.
* A classic token needs the `read:org` scope.

This notice applies to personal access token connections. A GitHub App connection does not show it.

## Configuring the integration

Open the GitHub settings dialog from the integrations page to refine repository scope and detection patterns.

### Allowed repositories

You can also scope scanning to specific repositories through **Allowed repos (optional)**. Select repositories in the picker, or choose **Enter manually instead** and type each `owner/repo`, pressing Enter after each one.

Leave this field empty to scan all repositories available to the connection.

### AI co-author detection patterns

The AI-versus-human split counts merged pull requests. A pull request is attributed to AI when a configured pattern matches a `Co-Authored-By` trailer on one of its commits. The product also checks matching markers in the pull request description and commit author email. A pull request without a matching signal counts as human-authored, even if an assistant helped create it.

This is attribution at the pull-request level, not a count of lines written by AI. GitHub does not expose line-level AI authorship through this integration. To make the split consistent, use each assistant's managed settings to add its co-author trailer to every AI-assisted commit across your organization. Then add any additional signature under **Integrations > Integrations > GitHub > Settings > AI co-author detection patterns**. A company-wide setting is more reliable than asking each developer to enable attribution locally.

Matching is case-insensitive substring matching on commit messages and on the pull request description, and exact matching on email addresses. An assistant with no signature recognized reads **Not detected** on its tab rather than showing a zero.

Claude Code, Cursor, and Codex CLI each ship with a built-in signature and need no configuration. Claude Code recognizes five signals automatically:

* the `noreply@anthropic.com` co-author email on a commit
* a `Co-Authored-By: Claude Code` trailer carrying no email address
* a `Claude-Session:` trailer
* commits authored by the `claude[bot]` GitHub identity
* a "Generated with Claude Code" footer in the pull request description

Cursor and Codex CLI are each recognized by their own default co-author email.

The pattern field on this settings dialog (one pattern per line, each at least 3 characters) feeds the **overall AI-assisted count**, the one that splits merged PRs into AI-assisted and human-authored. Patterns you add here extend the built-in signals behind that count and never replace them, and they add to no individual assistant's column. Use this field for a proxy address or an internal template your team wraps around AI-assisted commits, for example:

```
noreply@anthropic.com
claude-proxy@yourcompany.com
```

{% hint style="info" %}
This field is configured at the organization level and applies to every developer's figures, with no per-team variant. An individual assistant's own signature, the one behind its **PRs with \[Assistant]** column, is extended through the integration metadata API, keyed by assistant. The settings dialog has no field for that yet.
{% endhint %}

Check that your assistant actually adds its signature to commits or pull request descriptions. The managed setting that makes it add a trailer belongs in the assistant's organization settings; the GitHub settings dialog in Revenium controls which signatures to detect.

### Managing user mappings

Most developers are mapped for you. Revenium reads the mapping GitHub already holds. People are matched to their GitHub accounts without anyone editing anything, and without relying on a public profile or on a commit email that is usually private. Connecting GitHub starts that mapping immediately rather than waiting for the overnight sync.

Two things are worth knowing. The **token used to connect must be created by a GitHub organization owner for the identity list to be readable**. A mapping you set by hand is never overwritten by the automatic one.

If the automatic mapping cannot resolve someone, or if they commit under more than one address, you can adjust the mapping directly rather than leaving the attribution wrong.

* **Edit an existing mapping** to correct which Revenium user a GitHub identity resolves to.
* **Map multiple GitHub accounts to one corporate email**, so a developer who commits from more than one GitHub account still rolls up to a single person.

Consolidating accounts this way keeps per-developer metrics — PRs merged, PRs with AI assistance, and cost per PR — accurate for people who work across more than one GitHub identity.

## Department filtering and PR scope

The department filter on a coding assistant dashboard applies to AI completion metrics (sessions, tokens, cost). PR data is organization-wide: the PRs Merged and PRs with \[Assistant] columns reflect the developer's activity across the organization (or across your allowed repositories list), without the department filter. To limit PR scope to specific repositories, add those repositories to **Allowed repos (optional)**.

## Network requirements

If your GitHub enterprise uses an [IP allow list](https://docs.github.com/en/enterprise-cloud@latest/admin/configuring-settings/hardening-security-for-your-enterprise/restricting-network-traffic-to-your-enterprise-with-an-ip-allow-list), GitHub refuses any connection from an address that is not on it, including Revenium's. Add every address listed on [Revenium Outbound IP Addresses](https://docs.revenium.io/integrations/outbound-ip-addresses.md).

An enterprise owner adds them under the enterprise's **Settings → Authentication security → IP allow list**. If your organization manages its own list, an organization owner adds them under the organization's **Settings → Authentication security → IP allow list**. Entries on an enterprise list apply to every organization in the enterprise. See GitHub's guides to [enterprise](https://docs.github.com/en/enterprise-cloud@latest/admin/configuring-settings/hardening-security-for-your-enterprise/restricting-network-traffic-to-your-enterprise-with-an-ip-allow-list) and [organization](https://docs.github.com/en/enterprise-cloud@latest/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/managing-allowed-ip-addresses-for-your-organization) IP allow lists.

{% hint style="info" %}
If GitHub rejects your token as invalid and you have an IP allow list, check that Revenium's outbound addresses are approved. An address that is not on the list can look like a bad token.
{% endhint %}

## Troubleshooting

**No PR data appears after connecting:**

* Select **Sync now** on the GitHub card, or wait for the next scheduled pass. A new connection loads up to 90 days in hourly passes before its first figures are complete, and the card says **Still loading pull requests** until then
* Open **View Sync Logs** and select **Failures** to see whether a run failed and the suggested next step
* Confirm the token carries the permissions listed in [Prerequisites](#prerequisites) above. The connection screen can show a missing-permission error
* Verify the token is valid and not expired. The GitHub card shows when the token was last validated

**Coding assistant-attributed PR count is lower than expected:**

* A PR is attributed to an AI Coding assistant only if a matching signature appears on one of its commits or in the pull request description. This is user or organization-configurable, and not all Claude Code sessions automatically produce these — check whether those PRs carry the trailer or the description marker
* Confirm the repositories containing the expected PRs are accessible to your token (or listed in Allowed repos)
* Inspect the relevant repository to confirm whether the Co-Authored-By trailer or the pull request description marker appears where you expected it to count

**Developer PR counts are not attributed correctly:**

* If a developer is not mapped automatically, review their mapping on the **Integrations** tab and assign their GitHub account to the right corporate email
* Developers who use more than one GitHub account can have those accounts mapped to the same corporate email


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.revenium.io/track-and-control-costs/analyze-ai-tooling-spend/github-integration.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
