> For the complete documentation index, see [llms.txt](https://docs.forestall.io/forestall/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.forestall.io/forestall/configuration-center/github-configurations.md). # 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/`. * **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: — 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](#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: ` 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**).