Skip to main content
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. For read-only security analysis of non-human identities, see GitHub (NHI).
GitHub (Multi-Auth) is in beta and enabled per organization. Contact your Lumos representative to request access.
Entitlement IDs in this connector differ from the 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.

​
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

​
Entitlement model

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

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