Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

GitHub Configurations

GitHub Integration – Step-by-Step Requirements

To integrate FSProtect with GitHub, an authenticated identity with read access to your organizations, repositories, teams and roles must be provided. FSProtect supports two authentication methods: a Personal Access Token (PAT) or a GitHub App. This guide outlines how to create each, the required permissions, and how to configure them in FSProtect. GitHub Enterprise Cloud and GitHub Enterprise Server (on-prem) are both supported.

Step 1: Choose an Authentication Method

The authenticating identity should be (or the App should be installed by) an Organization Owner for complete visibility of organization- and repository-level security settings (2FA enforcement, member privileges, default repository permission, branch protection, secret scanning).

  • Personal Access Token (PAT) — quickest to set up; good for a single organization or a proof of concept.

  • GitHub App ⭐ — recommended for larger/enterprise deployments: read-only fine-grained permissions, higher rate limits, and one App can cover many organizations at once.

Step 2: Create a Personal Access Token (PAT)

  1. Sign in to GitHub and go to Settings → Developer settings → Personal access tokens.

  2. Choose Tokens (classic) and click Generate new token (classic).

  3. Give it a descriptive name (e.g., forestall-collector) and an expiration.

  4. Select the following scopes:

    • read:org — organizations, teams, memberships, organization roles, and org security settings.

    • repo — repositories (including private) and their security configuration (branch protection, secret scanning, Dependabot).

    • admin:org — read the organization's security settings (2FA requirement, default repository permission, MFA-disabled members). (Classic admin:org grants read-equivalent access for these org-level settings.)

    • read:enterprise — only if you will set an Enterprise Slug (to discover member organizations at the enterprise level).

  5. Click Generate token and copy the token.

⚠️ The token is shown only once. Save it securely before leaving the page.

Fine-grained PAT alternative: grant read-only access with Organization permissions: Members (read), Administration (read) and Repository permissions: Metadata (read), Administration (read), Secret scanning alerts (read).

Step 3: (Alternative) Create a GitHub App

If you prefer a GitHub App instead of a PAT:

  1. Go to Organization Settings → Developer settings → GitHub Apps → New GitHub App.

  2. Set a name (e.g., Forestall Collector) and a homepage URL (any valid URL).

  3. Under Permissions (read-only), grant:

    • Organization: Members, Administration (optionally Custom organization roles for org-role analysis)

    • Repository: Metadata, Administration (optionally Secret scanning alerts for GitHub Advanced Security checks)

  4. Create the App, then note the App ID (GitHub App → General → "App ID").

  5. Generate a Private Key — a .pem file downloads. Save it securely.

  6. Install the App on the organization(s) you want to scan (Install App → choose each org → All repositories).

You only need the App ID and the Private Key. You do not need to provide an Installation ID — FSProtect discovers every installation automatically (GET /app/installations) and scans each organization the App is installed on. Install the App on additional orgs anytime; the next scan picks them up with no config change.

⚠️ Install at the organization level — not the enterprise level. An enterprise-level installation grants only enterprise-scoped permissions and cannot read organization members, teams, repositories, or their security settings. Each organization's owner installs (or approves) the App on that org.

Step 4: (Enterprise) Determine Your Enterprise Slug

If you want FSProtect to discover all organizations within a GitHub Enterprise automatically, note your enterprise slug — it appears in the enterprise URL: github.com/enterprises/<slug>.

  • PAT: requires the read:enterprise scope and an enterprise-member/owner token.

  • GitHub App: the App already enumerates every organization it is installed on; leave this empty unless you specifically use an enterprise-installed App for org discovery.

Leave it empty to scan only the organizations the token/App can already access.

Step 5: GitHub Configuration in FSProtect

Navigate to Settings → GitHub Configuration in FSProtect, click Add, and fill in the fields.

Fields

Field
Auth
Description

Name

Both

A descriptive label for this configuration (e.g., "Acme prod PAT").

Enterprise Slug (optional)

Both

Set to scan every org in a GitHub Enterprise. Leave empty to scan all orgs the token/App can access.

Enterprise Server URL (optional)

Both

Set only for on-prem GitHub Enterprise Server. Leave empty for GitHub Cloud (api.github.com).

Verify TLS certificate

Both

Uncheck only for self-signed on-prem certificates (not recommended for production).

Authentication Method

—

Personal Access Token (PAT) or GitHub App.

Personal Access Token

PAT

The classic/fine-grained PAT. Its expiration is detected and shown next to the field.

App ID

App

The GitHub App's numeric App ID. Required.

Installation ID (optional)

App

Not required — auto-discovered. Leave empty.

Private Key (PEM)

App

Upload the .pem (drag & drop) or paste it. App private keys do not expire — rotate manually.

Accessible Organizations — after Test, FSProtect lists every organization the token/App can reach, with its id and whether it will be scanned.

Actions

  • Test — Validates the configuration by authenticating and verifying access (permissions, reachable organizations, token expiration). Use this before saving.

  • Save — Persists the configuration.

Best Practices

  • Least Privilege — Grant only the read scopes/permissions required for FSProtect to function.

  • Prefer a GitHub App — For larger or enterprise deployments, prefer a GitHub App over a long-lived PAT for better security, higher rate limits, and multi-org coverage from a single App.

  • Token / Key Rotation — Regularly rotate PATs and App private keys (recommended every 90 days or per your security policy). Always set a PAT expiration; FSProtect surfaces it so you can rotate before it lapses.

  • Dedicated Identity — Use a dedicated service account / App rather than a personal user's token.

  • Enterprise Scope — Only set an Enterprise Slug (and read:enterprise) when you intend to scan the whole enterprise.

  • Testing — Always use the Test button to validate the configuration before saving.

Troubleshooting

Authentication Fails

  • Verify the token has not expired or been revoked, and that the required scopes are selected.

  • For a GitHub App, confirm the App ID and Private Key (PEM) belong to the same App, and that the App is installed on the organization. (No Installation ID is needed.)

Permission Denied / Missing Data

  • Confirm the identity is an Organization Owner (or the App has Administration: read) — otherwise org-level security settings and repository security status may be missing.

  • Ensure repo (or Repository Administration/Metadata permissions) is granted so private repositories and their protections are visible.

Some Enterprise Organizations Not Scanned

  • FSProtect scans the organizations the App is installed on. Orgs shown as "App not installed" belong to the enterprise but need the App installed on them first — an owner of that org must install/approve it.

  • An enterprise-level App installation cannot scan org internals; install the App on each organization.

Enterprise Not Discovered (PAT)

  • Confirm the Enterprise Slug is correct, the token has the read:enterprise scope, and the identity is an enterprise member/owner.

On-Prem (Enterprise Server) Connection Fails

  • Verify the Enterprise Server URL is reachable from the FSProtect collector.

  • If the server uses a self-signed certificate, either install a trusted certificate or disable Verify TLS certificate (not recommended for production).

  • The URL must include a scheme (https://…); a bare host is not valid.

Configuration Won't Save

  • Ensure all required fields for the selected Auth Method are filled (PAT: token; App: App ID + Private Key).

  • Check that Test passes successfully before saving.

Required GitHub Permissions

Capability (PAT scope)
GitHub App equivalent
Purpose

read:org

Organization → Members (read)

Organizations, teams, memberships, org roles, member/2FA status, outside collaborators.

repo

Repository → Metadata (read) + Administration (read)

Repositories (incl. private) and their security config: branch protection, secret scanning, Dependabot.

admin:org

Organization → Administration (read)

Org security settings: 2FA requirement, default repository permission, MFA-disabled members.

Optional Capabilities (unlock additional checks when available)

  • audit_log (App: Organization → Administration read) — organization audit log; enables Inactive User detection (FS6001).

  • advanced_security (App: Repository → Secret scanning alerts read) — GitHub Advanced Security; enables Secret Scanning checks (FS6022 / FS6023).

  • Organization → Custom org roles (read) (App) — enables custom organization-role (GHOrgRole) analysis.

Conditional Permission

  • read:enterprise — read access at the enterprise level. Required only when an Enterprise Slug is configured (PAT), to discover all member organizations within a GitHub Enterprise.

⚠️ For complete visibility of organization-wide security settings (2FA enforcement, default repository permission, member privileges) and repository security status, the authenticating identity should hold Organization Owner rights (or the App must have Administration: read).

PreviousAudit Logs
NextAI Model Configuration

Last updated

Was this helpful?