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

# GitHub Multi-Auth

*This article covers the multi-auth GitHub connector ("GitHub (Multi-Auth)"). It signs in as a **GitHub App** with an App ID and a PEM private key, and syncs every organization the App is installed on, so one connection can cover many organizations. No installation ID is needed. For the OAuth-based connector, see [GitHub](/integrations/library/github). For read-only security analysis of non-human identities, see [GitHub (NHI)](/integrations/library/non-human/github-nhi).*

> GitHub (Multi-Auth) is in beta and enabled per organization. Contact your Lumos representative to request access.

<Warning>
  Entitlement IDs in this connector differ from the [GitHub](/integrations/library/github) connector. For example, repository roles use GitHub's `push` and `pull` permission names instead of `write` and `read`. Access history doesn't carry over between the two connectors, so switching from GitHub to GitHub (Multi-Auth) starts entitlement history fresh.
</Warning>

## After this article

You will be able to connect one or more GitHub organizations to Lumos through a GitHub App to sync members, outside collaborators, organization roles, teams, repository roles, and enterprise teams. You can also invite, remove, and change access for users from Lumos.

## Capabilities

| Functionality | Type | Sync | Provision | Description |
| :- | :- | :- | :- | :- |
| Users | Account | Yes | Yes | Organization members and, unless excluded, outside collaborators. The account ID is the GitHub login |
| Organization | Resource | Yes | No | One resource per organization the App is installed on |
| Organization Role | Permission | Yes | Yes | `admin`, `member`, `billing_manager`, and the synthetic `outside_collaborator` role |
| Team Role | Permission | Yes | Yes | `maintainer` and `member` on each organization team |
| Repository Role | Permission | Yes | Yes | Direct repository collaborator permissions: `admin`, `maintain`, `push` (Write), `triage`, and `pull` (Read) |
| Enterprise Team Role | Permission | Yes | Yes | `member` on each enterprise team. Requires the App to be installed on the enterprise |
| Last Activity | Usage | Yes | No | Last activity from the organization audit log. Only for organizations on GitHub Enterprise Cloud |

| Deprovisioning Action | Type | Description |
| :- | :- | :- |
| Delete | User | Removes the user from every organization as a member, or as an outside collaborator where they aren't a member, and cancels pending invitations |
| Unassign Role | Permission | Removes an organization, team, repository, or enterprise team role |

### Entitlement model

| Entitlement type | ID format | Values |
| :- | :- | :- |
| `ORG_ROLE` | `{org}/{role}` | `admin`, `member`, `billing_manager`, `outside_collaborator` |
| `TEAM_ROLE` | `{org}/{team}/{role}` | `maintainer`, `member` |
| `REPO_ROLE` | `{org}/{repo}/{permission}` | `admin`, `maintain`, `push`, `triage`, `pull` |
| `ENTERPRISE_TEAM_ROLE` | `{team}/member` | `member` |

* **Repository roles** only reflect direct repository collaborators. Access that comes from organization ownership, a team, or the organization's base permission isn't reported per repository. It shows under the organization and team roles instead.
* **Enterprise team roles** are managed at the enterprise level, so they're global entitlements with no organization resource. Lumos lists them as soon as the App is installed on the enterprise. No setting is needed.

### Entitlements you can't assign

* **`billing_manager`:** GitHub only allows billing managers to be invited, so Lumos lists this organization role as not assignable. Use Create Account with the Billing Manager role instead.
* **Teams managed by your identity provider:** organization teams that use team sync, and enterprise teams linked to an IdP group, are listed as not assignable. Manage their membership in your identity provider.

### Provisioning behavior

* **Create:** Lumos sends an organization invitation to the user's email with the selected organization role. Create Account requires exactly one `ORG_ROLE` entitlement. `outside_collaborator` can't be used as the create role. The account shows **Pending** until the user accepts the invite.
* **Assign an org role:** Lumos invites the user or updates their organization membership. Assigning `outside_collaborator` converts an existing organization member to an outside collaborator. To give a non-member outside collaborator access, assign a repository role instead.
* **Assign a team role:** team roles only apply to organization members. Organization owners can only be assigned as team maintainers.
* **Assign a repository role:** organization owners can only be assigned as repository admins.
* **Unassign an org role:** removes the user from the organization. If the user's membership comes from an enterprise team, Lumos removes nothing and returns a conflict that names the teams. Unassign the enterprise team roles first, then unassign the organization role again.
* **Unassign a repository role:** removes the direct collaborator grant. Access from ownership or the base permission isn't affected.
* **Delete:** if an enterprise team gives the user access to an organization, Lumos removes nothing and returns a conflict that names the teams.
* Writes are idempotent. When the state already matches, Lumos reports a no-op instead of an error.

## Required plan and roles

* **GitHub plan:** no minimum plan for sync and provisioning. Last activity requires GitHub Enterprise Cloud on each organization. Enterprise teams require the App to be installed on a GitHub Enterprise Cloud enterprise.
* **Hosting:** `https://api.github.com` by default. GitHub Enterprise Cloud with data residency (`https://api.<enterprise>.ghe.com`) and GitHub Enterprise Server (`https://<hostname>/api/v3`) are supported through the **API Base URL** setting.
* **Who sets it up:** an organization owner (or a member allowed to manage the organization's GitHub Apps) registers the App under the organization. On GitHub Enterprise Cloud, an enterprise owner can register it under the enterprise instead. An owner of each organization installs it.
* **GitHub App permissions:**

| Permission | Level | Used for |
| :- | :- | :- |
| Organization > Members | Read and write | Members, outside collaborators, teams, team roles, and invitations. Read-only is enough to sync, but teams managed by your identity provider are then listed as assignable and accounts can't be provisioned |
| Organization > Administration | Read-only | Organization audit log for last activity (GitHub Enterprise Cloud only) |
| Repository > Administration | Read and write | Adding and removing repository collaborators. Only needed to assign and remove repository roles |
| Enterprise > Enterprise teams | Read and write | Enterprise teams and their members. Read-only is enough to sync. Only for Apps installed on an enterprise |

Repository and collaborator listings only need the Metadata permission every GitHub App has.

## Read-only access vs provisioning

**Is read-only possible?** Yes. Grant **Organization > Members** and **Enterprise > Enterprise teams** as Read-only, and skip **Repository > Administration**. The connection validates and syncs. Write actions that need the missing permissions fail.

**What read-only requires.** A GitHub App with **Organization > Members: Read-only**, plus **Organization > Administration: Read-only** for last activity and **Enterprise > Enterprise teams: Read-only** for enterprise teams.

**What full provisioning requires.** **Organization > Members: Read and write**, **Repository > Administration: Read and write**, and, for enterprise teams, **Enterprise > Enterprise teams: Read and write**.

**Watch out for.** With **Organization > Members** set to Read-only, Lumos can't tell which teams your identity provider manages, so every team is listed as assignable. Install the App with **All repositories** on each organization, or repository roles won't sync. Lumos rejects the connection if any organization installation has no repository access or lacks a required read permission.

## Instructions

**Phase 1: Register the GitHub App**

Choose where to register the App:

* **Option A: one organization.** Register the App under the organization. To sync several organizations without an enterprise, register one App per organization and create one Lumos connection per App.
* **Option B: several organizations (GitHub Enterprise Cloud).** Register the App under the enterprise and install it on each organization.

1. Open the settings page:
   * **Option A:** click your profile picture, open **Your organizations**, and click **Settings** next to the organization. In the left sidebar, click **Developer settings → GitHub Apps**.
   * **Option B:** click your profile picture, open **Your enterprises**, and click **Settings** next to the enterprise (with Enterprise Managed Users, open **Your enterprise**). In the left sidebar, under **Settings**, click **GitHub Apps**.
2. Click **New GitHub App**.
3. Enter a name and any homepage URL, and uncheck **Active** under **Webhook**.
4. Under **Permissions**, set the permissions in the table above. Add **Enterprise permissions → Enterprise teams** only for Option B.
5. For Option A, keep **Only on this account** under **Where can this GitHub App be installed?** Choosing **Any account** lets any GitHub organization install the App and be synced into this connection.
6. Click **Create GitHub App**.

**Phase 2: Generate credentials**

1. On the App's settings page, under **About**, copy the **App ID**.
2. Under **Private keys**, click **Generate a private key**. GitHub downloads a `.pem` file.

**Phase 3: Install the App**

1. On the App's settings page, click **Install App**.
2. Click **Install** next to every organization to sync, and choose **All repositories**.
3. For Option B, also click **Install** next to the enterprise under **Install ... on an enterprise**. That installation enables enterprise teams and the higher rate limit.

**Phase 4: Connect in Lumos**

1. Go to **Settings → Integrations → GitHub (Multi-Auth)** and click **Connect**.

2. Enter the **App ID** and paste the full contents of the `.pem` file, including the `-----BEGIN` and `-----END` lines, into **Private Key**.

3. Optionally configure:
   * **App Identifier:** free text that tells apart several connections of the same App. Defaults to the App ID.
   * **Exclude Outside Collaborators** (default disabled): leaves outside collaborators out of accounts, entitlements, and associations.
   * **API Base URL** (default `https://api.github.com`): use `https://api.<enterprise>.ghe.com` for data residency or `https://<hostname>/api/v3` for Enterprise Server.
   * **Sync last activity** (default enabled): turn off if per-account audit log requests make the sync too slow.

4. Click **Connect**.

## API Endpoints Used

<Note>
  The API endpoints this integration uses are available to logged-in Lumos customers. [Log in](/login) to view them.
</Note>

## Troubleshooting

**"GitHub App ID or Private Key is invalid."** GitHub rejected the signed request. Check the App ID, and paste the full `.pem` contents including the `BEGIN` and `END` lines. Generate a new private key if needed.

**"The GitHub App is not installed on any organization."** Install the App on every organization that should be synced, then connect again.

**"The installation on the organization ... has access to no repository."** Open the organization's installation page and set **Repository access** to **All repositories**.

**"The installation on the organization ... is missing permissions."** Update the App's permissions, then approve the new permissions on each organization's or enterprise's installation page.

**Every team is listed as assignable, including IdP-synced teams.** **Organization > Members** is Read-only. Set it to **Read and write** so Lumos can detect teams managed by your identity provider.

**Unassign or Delete fails with a conflict naming enterprise teams.** The user's organization membership comes from an enterprise team, so removing it wouldn't revoke access. Unassign the enterprise team roles first, then retry.

**No last activity data.** Last activity only works for organizations on GitHub Enterprise Cloud, and only looks back over the audit log's 180-day retention. Accounts idle for longer report no activity. Check that **Sync last activity** is enabled and that the App has **Organization > Administration: Read-only**.

**An organization is missing from the sync.** Lumos skips suspended installations. Unsuspend the App on that organization. Writes to a suspended organization or enterprise fail with a permission error.

**Rate limits.** GitHub allows 5,000 requests per hour per installation, or 15,000 when the App is installed on a GitHub Enterprise Cloud enterprise, plus a separate 1,750 per hour budget for the audit log. Lumos retries rate-limited requests with backoff. Turn off **Sync last activity** if syncs are slow.