---
title: "Github (v2)"
slug: "github-v2"
description: "Customer-facing setup instructions: what a GitHub organization owner must install and approve, and what to expect in Clarity."
updated: 2026-10-09T16:08:22Z
published: 2026-10-09T16:08:22Z
canonical: "help.claritysecurity.com/github-v2"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://help.claritysecurity.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Github (v2)

## Overview

The Clarity GitHub connector reads your **organization members** and the access they hold — **org roles**, **teams**, and **repository permissions** — and, when NHI discovery is enabled, the organization’s **non-human identities**: GitHub App installations, fine-grained personal access tokens, repository deploy keys, bot members, and (on Enterprise Cloud) SAML-authorized classic PATs, SSH keys, and OAuth app tokens.

| What Clarity syncs / writes | GitHub REST source | Direction |
| --- | --- | --- |
| Org members (incl. bot members) | GET /orgs/{org}/members | read |
| Pending invitations | GET /orgs/{org}/invitations | read |
| Teams, team members, team repos | GET /orgs/{org}/teams[/{slug}/members\\|/repos] | read |
| Repositories + custom repo roles | GET /orgs/{org}/repos · /custom-repository-roles | read |
| Repository collaborators | GET /repos/{owner}/{repo}/collaborators | read |
| GitHub App installations *(NHI)* | GET /orgs/{org}/installations | read |
| Fine-grained PATs + their repos *(NHI)* | GET /orgs/{org}/personal-access-tokens[/{id}/repositories] | read |
| Deploy keys *(NHI)* | GET /repos/{owner}/{repo}/keys | read |
| SAML-authorized credentials *(NHI)* | GET /orgs/{org}/credential-authorizations | read |
| Invite a member / set org role | POST /orgs/{org}/invitations · PUT /orgs/{org}/memberships/{user} | write |
| Add / remove team membership | PUT · DELETE /orgs/{org}/teams/{slug}/memberships/{user} | write |
| Add / remove repo collaborator | PUT · DELETE /repos/{owner}/{repo}/collaborators/{user} | write |
| Remove a member from the org | DELETE /orgs/{org}/members/{user} | write |
| Revoke a fine-grained PAT *(NHI)* | POST /orgs/{org}/personal-access-tokens/{id} | write |
| Delete a deploy key *(NHI)* | DELETE /repos/{owner}/{repo}/keys/{id} | write |
| Revoke a SAML-authorized credential *(NHI)* | DELETE /orgs/{org}/credential-authorizations/{id} | write |

Clarity creates these **entitlement types** from the data: role (org role), team, repo_permission, and — for NHIs — app_permission.

**Authentication: there is nothing to type in.** No API key, no client secret, no private key, and (unlike the v1 connector) **no installation ID to copy**. Clarity authenticates as a **GitHub App that Clarity owns and operates**, using short-lived installation tokens brokered by Clarity’s GATE service. Setup is a single **App installation** in your organization.

## Prerequisites

- A **GitHub organization owner**. GitHub only permits an owner to install an App on an organization and to grant organization-level permissions.
- For classic-PAT / SSH-key / OAuth-token discovery only: **GitHub Enterprise Cloud with SAML SSO enabled** (see [Step 4](/docs/github-v2#Xddac80ebf8bb7984d42a344d9bffd78b0b45206)).
- In Clarity: permission to add an application (Admin).

You do **not** need to create a GitHub App, generate a private key, mint a PAT, or configure a callback URL. Clarity’s App registrations already exist; you are installing one of them.

## Step 1 — Add the integration in Clarity

1. Go to **Applications → Add Application** and choose **GitHub**.
2. Give it a name and unique identifier.
3. Under connector version, choose **v2 (Saloon)** — the recommended version. v1 (Legacy) still asks for an app_installation_id by hand; v2 does not.
4. Choose a **Trust Permission**. On GitHub this does more than set a Clarity-side boundary: **it selects which of Clarity’s three GitHub App registrations you are about to install**, and each one requests a different permission set from GitHub.

| Trust Permission | Effect for GitHub |
| --- | --- |
| **Read Only** | Sync members, teams, repos, and NHIs. No writes. |
| **Read + Provision/De-provision Entitlements (No User Creation)** | The above, plus team membership, repo collaborator, and org-role changes, and NHI offboarding. |
| **Read + Provision/De-provision Entitlements and Users** | The above, plus inviting new members and removing members from the organization. |

- **Choose this before you install.** Because the trust level picks a different GitHub App, changing it later is not a toggle — the installation you already approved belongs to the App you installed at the time. Treat a trust-level change as requiring a fresh install, and confirm with Clarity support before switching a live connection.

**Save**. Clarity hands you off to GitHub.

## Step 2 — Install the Clarity GitHub App

1. Clarity redirects you to GitHub (via Clarity’s GATE service).
2. **Sign in as an organization owner.** If another GitHub account is signed in to that browser, use a private/incognito window — this is the most common cause of a failed setup.
3. Choose the **organization** to install into. One Clarity application corresponds to one GitHub organization.
4. On the repository-access prompt, choose **All repositories**.

- **This choice is not cosmetic.** With *Only select repositories*, Clarity cannot see repositories outside the selection, so their collaborators and **deploy keys are silently absent** from the sync. An installation scoped this way is also recorded without the “all repositories” access binding, so the NHI’s repository reach cannot be resolved — GitHub exposes no org-level API to enumerate a selected installation’s repositories.

1. Review the permissions and choose **Install**.
2. You are returned to Clarity, which records the **installation ID** and **organization name** automatically and stores the connection.

## Step 3 — What the installation grants

These are **GitHub App installation permissions**, set at install time (GitHub Apps do not use OAuth scopes for this). You cannot narrow the list — it is fixed by the App registration your trust level selected. The table exists so you can review what you are approving, and so that missing data can be explained later.

| Permission | Used for | What happens without it |
| --- | --- | --- |
| Members (read) | GET /orgs/{org}/members, memberships, invitations | Sync returns **zero users**; the credential test fails. |
| Members (write) | invite, remove, set org role | User provisioning fails; reads unaffected. |
| Administration — organization (read) | app installations, credential authorizations | **No App-installation NHIs**, and no classic-PAT lane at all. |
| Administration — organization (write) | revoking a SAML-authorized credential | NHI offboarding for classic PATs / SSH keys / OAuth tokens fails. |
| **Personal access tokens (read)** | GET /orgs/{org}/personal-access-tokens | **No fine-grained-PAT NHIs — reported as an empty result, not an error.** |
| **Personal access tokens (write)** | revoking a fine-grained PAT | Discovery still works; offboarding fails. |
| Metadata / Contents (read) | repositories, collaborators, team repos | No repo or repo_permission entitlements. |
| Administration — repository (read) | GET /repos/{owner}/{repo}/keys | **No deploy-key NHIs.** *(Permission name not verified against a live installation — the connector only records that a 403/404 here is tolerated.)* |

**The fine-grained-PAT permission is the one that goes wrong.** It is surfaced in the App’s settings as **“Personal access tokens”**, not under “Administration”. If it is missing — or granted on the App but **not yet accepted on your installation** — GitHub answers 403, and Clarity tolerates that so one permission gap cannot fail the whole sync. The cost is that a permanent gap looks exactly like *“this org has no fine-grained PATs.”* An org that genuinely uses PATs and reports zero should be checked here first.

### Upgrading an existing installation

If the Clarity App was already installed (for example, on the v1 connector) and Clarity later adds a permission, **GitHub does not apply it retroactively**. It raises a permission-change request that an organization owner must accept before the new lane returns data — until then, that lane reads as empty.

Check for a pending request in your organization’s settings under the installed GitHub Apps list; GitHub also emails organization owners when a request is raised. *(Exact console path not verified for this guide — look for a “review request” prompt on the Clarity App’s entry.)*

## Step 4 — (Optional) Classic-credential discovery: GHEC + SAML SSO

GET /orgs/{org}/credential-authorizations is the **only** route to a classic personal access token — the organization PAT API covers fine-grained tokens only. It is also where SSH keys, OAuth app tokens, and user-to-server tokens are discovered.

It returns data **only on GitHub Enterprise Cloud with SAML SSO enabled**. Without SSO the endpoint answers 200 with an empty list, so:

**An empty classic-credential result means “cannot see”, not “none exist”.** The two states are indistinguishable from the response. Do not read an empty classic-PAT population as an all-clear on a non-GHEC organization.

Nothing needs configuring in Clarity for this lane — if your org is GHEC with SAML SSO, it populates on the next sync.

## Step 5 — Credentials to enter in Clarity

The v2 connector declares **no credential fields**. The organization name and installation ID are captured from the App installation in Step 2 and stored with the connection; the org name is parsed back out of it on every sync.

For contrast, **v1 (Legacy)** requires one field — app_installation_id, copied by hand from the installation’s URL. If you are looking at that field, you are on the wrong connector version.

## Step 6 — Verify the connection

1. Use Clarity’s **Test credentials** action. It issues GET /orgs/{org}/members?per_page=1 — a pass confirms the installation token works and members are readable.
2. Run a sync. Clarity fetches members and invitations first, then walks teams, custom repo roles, repositories, collaborators, and (with NHI discovery on) installations, fine-grained PATs, deploy keys, and credential authorizations.
3. Confirm the entitlement types you expect are present **and have identities linked**. A type that is entirely absent maps to a specific missing permission in the Step 3 table.

Expect the first sync of a large organization to take a while: deploy keys have no bulk source, so Clarity asks per repository. It honours GitHub’s rate limit (5,000 requests/hour per installation) and backs off automatically.

## Troubleshooting

| Symptom | Likely cause |
| --- | --- |
| Install button is greyed out, or you cannot choose the organization | You are not an organization owner. Owner-level access is required to install an App and grant org permissions. |
| Sync returns zero users | Members (read) not granted, or the installation was removed on the GitHub side. Re-check the App under your organization’s installed GitHub Apps. |
| Members sync, but **no fine-grained PATs** | The most common gap: “Personal access tokens (read)” was never granted, or a permission-change request is sitting unaccepted. GitHub returns 403 and Clarity tolerates it, so nothing appears as an error. See [Step 3](/docs/github-v2#step-3--what-the-installation-grants). |
| **No classic PATs**, but you know they exist | Expected unless the org is Enterprise Cloud with SAML SSO enabled. See [Step 4](/docs/github-v2#Xddac80ebf8bb7984d42a344d9bffd78b0b45206). |
| **No deploy keys**, or only some repos have them | Either the installation is scoped to *Only select repositories*, or repository-administration read was not granted. Repos outside the selection are invisible. |
| Some repositories missing entirely | Same cause — repository selection at install time. Re-run the installation and choose **All repositories**. |
| App installations appear with no owner | **Expected.** GitHub does not report who installed an org-level App, so those NHIs are necessarily ownerless. |
| A GitHub App installation cannot be offboarded | **Expected.** GitHub has no REST endpoint to uninstall a third-party App; remove it from the organization’s GitHub Apps settings. Clarity logs a warning and reports failure rather than pretending it succeeded. |
| Provisioning fails while reads succeed | The Trust Permission is Read Only, or the selected trust level’s App lacks the write permission. |
| Sync slows or pauses under load | Expected — GitHub throttles at 5,000 requests/hour per installation; Clarity backs off and resumes. |
| Authentication errors with nothing changed in Clarity | The installation was deleted or suspended on the GitHub side, or an owner revoked it. Re-install from Clarity. Persistent failures with a healthy installation are a Clarity/GATE issue — escalate with your org name and the time of the attempt. |

## What Clarity does NOT do

- **No GitHub account creation.** Clarity *invites* an existing GitHub user to your organization by email (POST /orgs/{org}/invitations); GitHub accounts themselves are created by the user. An invitation also requires a role-type default entitlement on the application, and a validated email on the identity.
- **No account deletion or suspension.** GitHub’s only offboarding primitive for a human member is **removal from the organization** — so in Clarity, “deactivate” and “delete” perform the same action.
- **No org-role removal.** Roles can only be *changed* (member ↔ admin), never removed; there is no “no role” state for an org member.
- **No repository, team, or organization management.** Clarity never creates, renames, or deletes repos, teams, or orgs — only membership and permissions within existing ones.
- **No code, issues, pull requests, Actions, or secrets** are ever read.
- **No enterprise-level visibility.** The connector is scoped to one organization per Clarity application; enterprise-wide objects are out of scope.
- **No narrowing of the App permission set.** Permissions are fixed by the App registration your trust level selected — scope your exposure with the Trust Permission setting in Clarity instead.

## Need Help?

If you have any problems, contact your customer success team. You can also get in touch with our general support [via email](mailto:support@claritysecurity.io), open a [support ticket](https://support.claritysecurity.com/home). Our general support team is available Monday - Friday from 8:00 AM - 6:30 PM CST.