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.

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).

• 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.

• 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.

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

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?