GitHub & GitHub Advanced Security

Register a GitHub App per tenant, store credentials encrypted in SecureHive, install the app on your org or user account, then list repositories, import applications, and sync code scanning findings into Issues.

Overview

SecureHive uses a GitHub App (not a personal access token) so access is scoped to installations, supports security APIs, and can receive webhooks. Each tenant configures their own GitHub App credentials; nothing is stored in global environment variables.

Encrypted storage — App ID, app slug, PEM private key, and optional webhook secret are saved per tenant and encrypted using tenant-scoped keys / KMS.
Install URL — After configuration, SecureHive builds https://github.com/apps/<your-app-slug>/installations/new with a state parameter that binds the installation to your tenant.
Advanced Security — With appropriate GitHub plan and permissions, code scanning alerts can be synced into SecureHive as security Issues (e.g. source SAST), deduplicated by external alert ID.

Use a dedicated GitHub App for SecureHive. Grant only the repository and security permissions you need (e.g. metadata read, security events read for Advanced Security).

Create a GitHub App

Go to Settings → Developer settings → GitHub Apps → New GitHub App (or your org’s equivalent). Fill in every required field as below.

Basic information

GitHub App name (Required): Any name (e.g. “SecureHive Integration”). Users see this when installing.
Description: Optional. Short description of the app for the installation page.
Homepage URL (Required): Your SecureHive frontend or company URL, e.g. https://app.securehive.example.com.

Identifying and authorizing users

Callback URL (Required by GitHub): Use the SecureHive install callback — https://api.securehive.ai/api/integrations/github/callback. The tenant is identified by the state parameter.
Expire user authorization tokens: Can leave checked; SecureHive uses installation tokens, not user OAuth.
Request user authorization (OAuth) during installation: Leave unchecked. We use installation-only flow.
Enable Device Flow: Leave unchecked.

Post installation

Setup URL (optional but recommended): Set to the same callback URL so users are sent to SecureHive after installing: https://api.securehive.ai/api/integrations/github/callback. GitHub will append ?installation_id=...&setup_action=install&state=...; SecureHive uses state to bind the installation to your tenant.
Redirect on update: Optional. If checked, users are redirected to the Setup URL when they change repos.

Webhook

Active: Check only if you want real-time events (e.g. code_scanning_alert). Otherwise leave unchecked; you can still use “Sync security alerts” on demand.
Webhook URL (Required if Active): https://api.securehive.ai/api/integrations/github/webhooks (use webhooks with an “s” — /webhook will 404).
Secret: If webhook is active, use the Generate button in SecureHive (Settings → Integrations → GitHub → Edit configuration → Webhook secret) to create a random secret. Paste that same value here in the GitHub App’s Webhook secret field, then save in both places. SecureHive uses it to verify X-Hub-Signature-256.

Permissions

Under Repository permissions (and adjust Organization/Account if your app is org-level):

Permission	Access level	Purpose
Metadata	Read-only	Required for listing repos and installation info
Security events	Read-only	Required for code scanning / Advanced Security APIs and webhook events

Leave other permissions at “No access” unless you have a specific need.

You must set Security events to Read-only before security-related subscription options (e.g. Code scanning alerts) will appear under “Subscribe to events.”

Only relevant if Webhook → Active is checked. For code scanning alerts, enable Code scanning alerts so SecureHive can receive code_scanning_alert events. Other events (e.g. Security advisory, Meta) are optional.

Where can this GitHub App be installed?

Only on this account — Use this if the app is for a single org or your user only.
Any account — Use this if you want other GitHub users or orgs to be able to install the app (e.g. multi-tenant SaaS).

After creating the app

Note the App ID

On the app’s settings page, note the numeric App ID (e.g. 123456).

Find the App slug

Find it in the URL when you open your GitHub App’s settings page. The slug is the last path segment: github.com/settings/apps/<slug> (user) or .../organizations/<org>/settings/apps/<slug> (org).

Generate a private key

Under Private keys, click Generate a private key and download the PEM file. You will paste its contents into SecureHive once; store the file securely and do not commit it to source control.

Configure in SecureHive

Go to Settings → Integrations → GitHub (tenant administrators).

Open configuration

Click Add configuration or Edit configuration.

Enter credentials

Enter App ID, App slug, and paste the PEM private key.

Set webhook secret (optional)

Enter the Webhook secret if you configured webhooks on the GitHub App.

Save

Click Save. Secrets are encrypted and never returned to the browser after save.

Install & connect

After saving configuration, use Connect GitHub. You will be sent to GitHub to install the app on an organization or your user account. When GitHub redirects back to SecureHive, the installation is linked and you will see Connected with the account login and installation ID.

You can use List repositories on the same page to verify access.

Import repositories as Applications

Go to AppSec → Applications → Import from GitHub.

Select one or more repositories; SecureHive creates an Application per repo with name and repository URL. You can then attach threat models and map security findings to that application when repo URLs match.

GitHub Advanced Security sync

Code scanning alerts → SecureHive Issues (SAST).

On Settings → Integrations → GitHub, after the app is connected, use Sync security alerts to pull code scanning alerts from repositories your installation can access. Alerts are matched to Applications when the repository URL matches an Application’s Repository URL; duplicates are avoided using an external alert identifier.

Requires GitHub Advanced Security (or equivalent) on the repositories and correct GitHub App permissions for security APIs.

Webhooks (optional)

Set the GitHub App webhook URL to https://api.securehive.ai/api/integrations/github/webhooks. Store the same webhook secret in SecureHive so X-Hub-Signature-256 can be verified per tenant.

For production, use the raw request body for signature verification as recommended by GitHub.