Skip to main content

​
About GitHub

Serval’s GitHub integration connects your GitHub Organization, User account, or Enterprise to Serval so workflows can read repositories, manage teams, and call the GitHub API on your behalf. It authenticates exclusively through GitHub Apps - never personal access tokens. You choose between two Serval-managed apps with different access tiers, or bring a GitHub App owned by your own organization. Authentication: GitHub App installation only. Pick a Serval-managed app - Full Admin Access or Code Contributor Access - or choose Use Your Own GitHub App. The bring-your-own path offers two options: let Serval walk you through installing the app (Install with Serval), or connect an app your GitHub organization admin already installed out of band (App already installed) by pasting its credentials. Workflow API calls never rely on a stored long-lived token: a fresh, short-lived installation access token is minted for every call. Data sync: Workflow API calls run on demand. For Access Management, GitHub Teams are ingested on a fixed schedule every 16 hours, always as a full sync (GitHub does not support delta sync).

​
What the GitHub integration enables

Anything defined in the GitHub API can be accessed through Serval.

​
Get your credentials

What you need depends on which connect option you choose in the Connect GitHub modal.
Nothing to create. Both Full Admin Access (“Read contents of selected repos, open pull requests, create and manage repos and teams, invite users”) and Code Contributor Access (“Read contents of selected repos, open pull requests, and comment on issues”) use GitHub Apps that Serval manages - no credentials are required.
The install must be performed by (or approved by) a GitHub Organization Owner. If you’re not an owner, your install lands in a pending state until an owner approves it in GitHub - see Gotchas below.

​
Connect in Serval

1

Open the Connect GitHub modal

Click Connect on GitHub in Serval. The modal asks you to “Choose the access level that best suits your needs” - pick Full Admin Access or Code Contributor Access.
2

Install the app on GitHub

Serval opens GitHub’s install screen. Pick the target organization (or user or enterprise account), then choose all repositories or only selected repositories, and click Install & Authorize.
3

Return to Serval

GitHub sends you back to Serval, which records the installation and names the connection after your org or user login (or the enterprise slug for Enterprise installs). No credentials are ever entered.
Repository selection and access tier are fixed at install time. Repositories can be adjusted later in GitHub’s installed-apps settings; switching tiers requires uninstalling in GitHub and reconnecting with the other tier.

​
Verifying the connection

Serval runs three health checks against a connected GitHub integration:
  1. Test GitHub App Installation - verifies a token can be minted and works, by making a small test request (a sample of accessible repositories for org/user installs, or a single enterprise team for Enterprise installs).
    • Success: GitHub App installation for [name] is properly configured and functional - or, for enterprise installs, GitHub Enterprise App installation for [name] is properly configured and functional
    • Failure: GitHub App installation token for [name] is invalid or not working. followed by a status-specific hint:
      • 401 - The GitHub App installation token is invalid or expired. Please reinstall the GitHub App.
      • 403 - The GitHub App may not have the required permissions. Check the app's permission configuration.
      • 404 - The GitHub App installation was not found. It may have been uninstalled or it may be awaiting approval from an admin of [name]. Visit https://github.com/organizations/[name]/settings/installations for more info.
      • 500/502/503 - GitHub returned a server error. This is likely a temporary issue with GitHub's API - please try again later.
  2. List GitHub Teams - confirms the integration can list teams in the connected scope (org teams, or enterprise teams for Enterprise installs).
    • Success: Successfully listed [number] teams in [name] - or, for enterprise installs, Successfully listed [number] enterprise teams in [name]
    • Failure: Unable to list GitHub teams in [name]. followed by the same 401/403/server-error hints; the generic 404 variant reads The requested resource was not found. This may indicate missing permissions or incorrect configuration.
  3. List GitHub Repositories - confirms the integration can list accessible repositories for the org. Enterprise installs skip this check and report it as passing.
    • Success: Successfully listed [number] repositories for [name] - enterprise installs instead report Not applicable: this check only validates org/user installs. Enterprise install ([name]) covered by test-installation-token.
    • Failure: Unable to list GitHub repositories for [name]. followed by the same 401/403/404 (generic)/server-error hints.
If all three checks are green but a specific workflow still fails with a permission error, the cause is almost always install-time scoping: the access tier you chose (Full Admin vs Code Contributor), the repository selection (all vs selected), or - on Enterprise installs - workflows that require an organization install. Check the app’s settings in GitHub’s installed-apps page, and see the gotchas below.

​
Gotchas and troubleshooting

If the person connecting isn’t a GitHub Organization Owner, GitHub treats the install as a request and Serval creates a pending connection. Until an owner approves the app in GitHub, every API call fails with GitHub installation is pending approval. Once approved, the connection completes automatically - Serval matches the pending record even if the approval finishes outside the original browser session, returning the approver to Serval (or showing GitHub installation completed. You can close this window. when no return destination was recorded). If more than one pending install exists for the same GitHub target, completion errors with multiple pending installations found for this GitHub target - please keep only one.
If your security process requires an authorized org admin to install the reviewed app separately rather than inline during a vendor’s connect flow, use Use Your Own GitHub App → App already installed. Serval authenticates as the app via a signed JWT, so this path needs no OAuth callback and no client secret - only the App ID, Installation ID, and private key. There is no 10-minute credential window and no pending-approval handshake: the admin installs the app on GitHub first, then anyone with the credentials connects it in Serval. Because there is no OAuth ownership check on this path, possession of the private key is the authorization - treat it as a secret and use a dedicated, rotatable key.
For Use Your Own GitHub App, submitted credentials are held for only 10 minutes. If your org requires admin approval, the connection rejects with GitHub App installation is pending approval. Ask a GitHub organization owner to approve the app, then reconnect it in Serval. - your credentials are deliberately kept so an immediate retry works, but only until the 10 minutes expire, after which you’ll see Invalid or expired OAuth state and must resubmit the form.
On reconnect, Display name, GitHub App public link, App ID, and Client ID are prefilled, but Client secret and Private key PEM always start blank and are hard-required - submit is blocked and blanks are rejected with clientSecret is required / privateKey is required. There is no keep-existing-secret path. Have the .pem file and a client secret ready (or generate fresh ones in GitHub) before you start.
An Enterprise-scoped install is tied to the enterprise, not an organization. Workflows that inherently target an organization fail with This workflow requires a GitHub organization install, but the connected install is enterprise-scoped ([name]). Team ingestion returns an empty set for enterprise installs, the repository health check is reported as not applicable, and enterprise-only endpoints require the dedicated enterprise API action.
Team ingestion never creates new Serval users, because GitHub emails may be missing or personal. The Add GitHub User to Team workflow rejects anything that looks like an email address with Invalid GitHub username: '[username]'. Please provide a GitHub username (not an email address). GitHub usernames typically contain only letters, numbers, and hyphens. Access Management provisioning is likewise instructed never to guess: its input is annotated “The target user’s GitHub username. Do not make guesses about the user’s username. Ask the user for their GitHub username.”
Tokens are minted fresh for every API call, so an uninstall (or an unapproved install) surfaces right away as The GitHub App installation was not found. It may have been uninstalled or it may be awaiting approval from an admin of [name]. Visit https://github.com/organizations/[name]/settings/installations for more info.
Which repositories Serval can read is decided on GitHub’s install screen (all vs selected) and managed afterward in GitHub’s installed-apps settings, not in Serval. The two Serval-managed tiers are separate GitHub Apps - switching tiers means uninstalling the current app in GitHub and reconnecting with the other one.
GitHub does not support incremental sync, so every scheduled run re-enumerates all teams, their repositories, and memberships. Newly created GitHub teams appear after the next scheduled sync or a manual resync.
Need help? Contact support@serval.com for assistance with your GitHub integration.