GitHub App Integration Guide
The GitHub App integration is the recommended way to connect your repositories to Openlane. It uses installation-scoped, short-lived tokens instead of user OAuth credentials, which means tighter access control and no dependency on individual user sessions.
Key Capabilities
- Installation-Scoped Authentication: Uses app credentials to mint short-lived installation tokens, so there are no long-lived user tokens to manage or rotate.
- Repository Access Validation: Confirms installation visibility to target repositories so you know exactly what Openlane can see.
- Security Alert Ingestion: Collects Dependabot, code scanning, and secret scanning alerts, giving you a unified view for vulnerability tracking and remediation SLAs (SOC 2: CC7, CC8).
Prerequisites
- Permission to install the Openlane GitHub App in the target organization.
- Repository access for whichever repositories you want in scope.
Step-by-Step Setup
Step 1: Authorize the Openlane GitHub App
- Navigate to Organization Settings > Integrations and find GitHub App.
- Click Configure.
- Click Continue to Authorization — you will be redirected to GitHub. There are no credentials to enter manually.
- On GitHub, choose the organization where you want to install the app.
- Choose repository access scope:
- All repositories, or
- Only select repositories.
- Complete the installation. GitHub redirects back to Openlane automatically.
Step 2: Configure Sync Behavior
Optionally configure which data sources are active and how records are filtered before ingestion:
GitHub Security Hub Sync
| Setting | Description |
|---|---|
| Disable | Turn off vulnerability ingestion from GitHub Security without disconnecting the integration |
| Filter Expression | CEL expression evaluated against each vulnerability record — only records that match are ingested |
# Ingest only open alerts
payload.state == 'open'
Directory Account Sync
| Setting | Description |
|---|---|
| Disable | Turn off user and group ingestion from GitHub |
| Disable Group Sync | Sync GitHub users only — skip team/group membership |
| Filter Expression | CEL expression evaluated against each user record — only records that match are ingested |
# Limit to a specific org
payload.Org == 'my-org'
Repository Sync
| Setting | Description |
|---|---|
| Disable | Turn off repository ingestion from GitHub |
| Filter Expression | CEL expression evaluated against each repository record — only records that match are ingested |
# Ingest only repositories with open state
payload.state == 'open'
CEL expressions have access to the full raw payload for each record via payload.<field>.
Validate Connection
After saving, Openlane runs a health check against the GitHub App installation and displays the result on the Installed tab of the Integrations page. A Healthy badge confirms connectivity. If the badge shows Needs Attention, review the troubleshooting section below.
What Openlane Syncs
- GitHub Security Hub Sync: Collects Dependabot, code scanning, and secret scanning alerts and normalizes them into vulnerability records you can link to assets, assign to teams, and track against remediation SLAs (SOC 2: CC7, CC8; ISO 27001: A.12.6).
- Directory Account Sync: Pulls GitHub users and team membership into Openlane directory accounts, giving you visibility into who has access to your repositories.
- Repository Sync: Ingests repository metadata scoped to the app installation as assets within Openlane, providing an inventory of repositories within your compliance boundary.
Disconnect
To remove this integration:
- Navigate to Organization Settings > Integrations
- Select the Installed tab
- Open the menu on the integration card and select Disconnect.
This removes stored credentials and stops all collection activity and will redirect you to the installation in github to remove the installed app.
Troubleshooting
- No repository visibility: verify the app is installed in the correct org and includes the intended repositories.
- Missing alerts from expected repos: verify those repos are in the app installation scope and have GitHub security features enabled.
- Install prompt loops or access denied: verify you have permissions to install or manage apps in that organization.