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 scan GitHub, provide an authenticated identity with read access to your organizations, repositories, teams and roles. Two authentication methods are supported: 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 Forestall. 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 or enterprise deployments. It has 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. The scan discovers every installation automatically (GET /app/installations) and covers 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 Forestall 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 Forestall

Navigate to Configuration Center → GitHub → Manage in Forestall. The list shows the saved configurations with the Name, Enterprise and Auth Method columns. The three-dot menu of a row offers Edit and Delete (confirmed in the Confirm Delete Operation window). Click New Configuration and fill in the fields.

GitHub Configuration form with Required Permissions, Optional Capabilities and Accessible Organizations
GitHub Configuration (GitHub App, after Test)

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 (uncheck only for self-signed certificates)

Both

Shown only when Enterprise Server URL is filled in. 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. After Test, its expiration is shown under the label (Token expires: <date> — N days left, or — expired).

App ID

App

The GitHub App's numeric App ID. Required.

Installation ID (optional)

App

Not required, it is discovered automatically. Leave empty.

Private Key (PEM)

App

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

Required Permissions and Optional Capabilities panel

The right side of the form lists the Required Permissions (read:org, repo, admin:org) and the Optional Capabilities (audit_log, advanced_security). When GitHub App is selected, the labels change to the equivalent fine-grained permissions (for example Organization → Members (read)), and an extra optional capability, Organization → Custom org roles (read), is listed. Hover the ⓘ icon next to an item to see what it is used for. See Required GitHub Permissions for the full mapping.

Before the first test, every item has an orange ? icon and the panel shows "Click Test to detect token scopes and available capabilities." After Test, each item shows:

  • a green ✓: granted,

  • an orange ⚠ with N/M orgs: granted only on some organizations,

  • a red ✗ (required) or a grey – (optional): not granted.

Accessible Organizations (X/Y scanned): After Test, the form lists every organization the token/App can reach, with its id and one of the following states:

  • green ✓: the organization will be scanned.

  • App not installed — ask the org owner to install it: the organization belongs to the enterprise, but the App is not installed on it.

  • not licensed — won't be scanned: the organization is not covered by your Forestall license (license organization limit).

An organization can also show missing: <permissions> when a required permission is not granted on it. If none of the installed organizations is licensed, Save is disabled until at least one organization id is added to the license and Test is run again.

Actions

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

  • Save: Persists the configuration.

  • Delete: Shown only when editing an existing configuration.

Best Practices

  • Least Privilege: Grant only the read scopes/permissions required for Forestall 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; Forestall 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

  • The scan covers 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 Forestall 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 · audit log): Enterprise audit log (PAT) or organization audit log (App). Enables Inactive User detection (FS6001).

  • advanced_security (App: Repository → Secret scanning alerts read): GitHub Advanced Security. Enables Secret Scanning checks (FS6008 / FS6009).

  • 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).

PreviousDomain-Wide Delegation
NextCyberArk

Last updated

Was this helpful?