> 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 integrate Forestall ISPM with GitHub, an authenticated identity with **read access** to your organizations, repositories, teams and roles must be provided. Forestall 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 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/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 — Forestall 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 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 **Settings → GitHub Configuration** in Forestall, 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**, Forestall 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 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**

* Forestall 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 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)* — 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**).