> ## Documentation Index
> Fetch the complete documentation index at: https://support.configview.com/llms.txt
> Use this file to discover all available pages before exploring further.

# GitHub setup

ConfigView pulls GitHub data through **one Personal Access Token (PAT)** with enterprise-level scopes, plus your **enterprise slug**. The same PAT covers all 46 endpoints — there is no separate SCIM, billing, or audit credential.

You will end up with **2 secrets** in ConfigView (`GITHUB_TOKEN`, `GITHUB_ENTERPRISE_SLUG`) when setup is complete.

> **Plan requirement.** Most endpoints require a **GitHub Enterprise Cloud** subscription. A handful (`repos`, `repo_*`, `org_*` basics) work on Team or Free orgs too, but the enterprise-tier endpoints (audit log, billing, runners, Copilot, secret-scanning aggregation, members-by-consumed-license) only function for an Enterprise account. If you are not on Enterprise Cloud, you can still enable the org and repo endpoints — the enterprise ones will fail cleanly.

***

## Step 1: Identify your enterprise slug

Open [https://github.com](https://github.com) signed in as a GitHub user who is an **Enterprise Owner**.

1. Click your profile picture → **Your enterprises**
2. Click your enterprise
3. The URL is `https://github.com/enterprises/<slug>` — copy the `<slug>` portion

That slug is your `GITHUB_ENTERPRISE_SLUG`.

> If you do not see **Your enterprises**, you are not an Enterprise Owner on any enterprise. You can still proceed using **org-level** endpoints only — set `GITHUB_ENTERPRISE_SLUG` to any non-empty placeholder (e.g. `none`) and skip every script whose display name begins with **Enterprise**.

***

## Step 2: Create the Personal Access Token

ConfigView uses a **classic PAT** (not fine-grained) because GitHub's enterprise endpoints, audit log, and Copilot APIs are not yet supported under fine-grained PATs.

1. Sign in to GitHub as the **Enterprise Owner** identified in Step 1
2. Open [https://github.com/settings/tokens](https://github.com/settings/tokens)
3. Click **Generate new token** → **Generate new token (classic)**
4. **Note:** `ConfigView`
5. **Expiration:** pick a duration that matches your secret-rotation policy (90 days, 1 year, or custom)
6. **Select scopes:** check the boxes below. The scope you need depends on which endpoints you plan to enable — checking all of them is the simplest path:

| Scope                                   | Why                                                                 | Endpoints it unlocks                                                                                         |
| --------------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `read:enterprise`                       | Enterprise account + members + audit log                            | All Enterprise-prefixed endpoints                                                                            |
| `read:org`                              | Org structure, teams, members                                       | Organizations, Org Members, Teams, Team Members, Outside Collaborators                                       |
| `read:audit_log`                        | Org-level audit log                                                 | Org Audit Log                                                                                                |
| `admin:org` (read-only is implied)      | Webhooks, installations, fine-grained PATs, IP allow list, settings | Installed GitHub Apps, Fine-Grained PATs, Org Webhooks, IP Allow List, Org Settings, Org Actions Permissions |
| `repo`                                  | Private repo metadata, branch protection, env secrets (names only)  | Repositories (private), Branch Protection, Repo Secrets, Environments, Webhooks, Deploy Keys                 |
| `security_events`                       | Dependabot, code-scanning, secret-scanning alerts                   | Dependabot Alerts, Code Scanning Alerts, Secret Scanning Alerts (Org + Enterprise)                           |
| `manage_billing:enterprise`             | Enterprise billing endpoints                                        | Enterprise Billing — Actions / Packages / Shared Storage                                                     |
| `copilot` (or `manage_billing:copilot`) | Copilot seat + usage + billing                                      | Copilot Seat Assignments, Copilot Usage, Copilot Billing Summary                                             |
| `read:user`, `user:email`               | SSH/GPG/SAML key metadata for enterprise members                    | User SSH Keys, User GPG Keys, SAML/SSO Identities                                                            |

7. Click **Generate token**
8. Copy the token (starts with `ghp_...`). You will not be able to see it again — store it somewhere safe.

> **SAML SSO authorization.** If your enterprise enforces SAML SSO, after creating the token you must **authorize it for SSO**: on the token page, find the new token in the list and click **Configure SSO** → **Authorize** for your enterprise. Otherwise every API call returns `403`.

> **Read-only scopes only.** ConfigView never writes to GitHub. The scopes above let it call `GET` endpoints; the API has no concept of "read-only token," so a `repo` scope technically allows writes — but the scripts only issue reads.

***

## Step 3: Add the secrets to ConfigView

1. Go to your ConfigView dashboard: `https://{companyname}.configview.com/admin/secret/`
2. Click **Add Secret** and create:
   * `GITHUB_TOKEN`: the `ghp_...` token from Step 2
   * `GITHUB_ENTERPRISE_SLUG`: the slug from Step 1
3. Click **Save**

***

## Step 4: Enable the GitHub scripts in ConfigView

1. Go to: `https://{companyname}.configview.com/admin/cron/`
2. You should see **github** in the list of available apps
3. Select the scripts you want to run. Group them by tier — enable only the tiers that match your plan:

### Enterprise tier (Enterprise Cloud required)

| Script                                                       | Notes                                                                  |
| ------------------------------------------------------------ | ---------------------------------------------------------------------- |
| **Enterprise Account**                                       | Single row — name, billing email, created date                         |
| **Enterprise Owners & Billing Managers**                     | Who can administer the enterprise                                      |
| **Enterprise Members (Consumed Licenses)**                   | Authoritative seat count for billing reconciliation                    |
| **Enterprise Pending Invitations**                           | Outstanding invites that aren't consuming seats yet                    |
| **Enterprise Organizations**                                 | Every org under the enterprise. **Most other scripts depend on this.** |
| **Enterprise Audit Log**                                     | Last 30 days of enterprise-level admin events                          |
| **Enterprise Billing — Actions / Packages / Shared Storage** | Three separate scripts for the three billable units                    |
| **Enterprise Self-Hosted Runners**                           | Inventory of enterprise-level runners                                  |
| **Enterprise Runner Groups**                                 | Runner groups + which orgs/repos can use them                          |
| **Enterprise Secret Scanning Alerts**                        | Cross-org rollup                                                       |
| **Copilot Seat Assignments**                                 | Who has a Copilot seat                                                 |
| **Copilot Usage (Daily)**                                    | Daily active users, suggestions, acceptance rate                       |
| **Copilot Billing Summary**                                  | Seat count + per-seat cost                                             |

### Org tier (works on any GitHub Team or Enterprise org)

| Script                                                  | Notes                                                                                   |
| ------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| **Organizations**                                       | All orgs under the enterprise. **Almost every org/repo script depends on this.**        |
| **Org Members**                                         | Per-org member list with role (admin/member)                                            |
| **Outside Collaborators**                               | Non-members with access to org repos                                                    |
| **Org Pending Invitations**                             | Outstanding org invites                                                                 |
| **Teams**                                               | All teams in each org                                                                   |
| **Team Members**                                        | Membership of each team. Depends on Teams.                                              |
| **Team Repository Permissions**                         | Which repos each team has access to + at what permission. Depends on Teams.             |
| **Installed GitHub Apps**                               | GitHub Apps installed on the org (not OAuth)                                            |
| **OAuth Apps (from Audit Log)**                         | Extracted from `oauth_authorization.create` audit events — there is no direct API       |
| **Fine-Grained PATs**                                   | PATs that have access to org resources                                                  |
| **Org Webhooks**                                        | Webhooks configured at the org level                                                    |
| **Org Secrets (Names)**                                 | Names only — GitHub never returns secret values                                         |
| **Org Actions Variables**                               | Workflow variables at the org level (names + visibility)                                |
| **Org Actions Permissions**                             | Which actions allowed, default workflow permissions                                     |
| **Security Manager Teams**                              | Teams granted the security-manager role                                                 |
| **Custom Repository Roles**                             | Org-defined custom roles                                                                |
| **Dependabot / Code Scanning / Secret Scanning Alerts** | Three separate scripts for the three alert kinds (org rollup)                           |
| **IP Allow List**                                       | Enabled status + entries                                                                |
| **Org Audit Log**                                       | Last 30 days of org-level events. **Same source as OAuth Apps — enable both together.** |
| **Org Settings**                                        | Misc org settings (default repo permission, member privileges, etc.)                    |

### Repo tier

| Script                                 | Notes                                                                         |
| -------------------------------------- | ----------------------------------------------------------------------------- |
| **Repositories**                       | Every repo across every visible org. **All repo\_* scripts depend on this.*\* |
| **Branch Protection (Default Branch)** | Default branch only — feature/release branches are not walked                 |
| **Repo Secrets (Names)**               | Names only                                                                    |
| **Repo Environments**                  | Environments + their protection rules                                         |
| **Repo Collaborators**                 | Per-repo direct + team-derived access                                         |
| **Repo Webhooks**                      | Repo-level webhooks                                                           |
| **Repo Deploy Keys (Metadata)**        | Fingerprints, last-used dates — never the private key                         |

### User tier

| Script                  | Notes                                                                       |
| ----------------------- | --------------------------------------------------------------------------- |
| **User SSH Keys**       | Per enterprise-member SSH key metadata. Depends on Enterprise Members.      |
| **User GPG Keys**       | Per enterprise-member GPG key metadata. Depends on Enterprise Members.      |
| **SAML/SSO Identities** | Mapping between GitHub user and SAML NameID. Depends on Enterprise Members. |

4. Click **Save**

> **Note:** ConfigView wires the parent-child dependencies automatically (e.g. `org_members` runs after `organizations`). You only need to make sure the parent script is enabled when you enable a child.

***

## Step 5: Verify

1. Go to: `https://{companyname}.configview.com/admin/status/`
2. Run the **GitHub** health check
3. The check should pass with your enterprise name + at least one organization listed

If a check fails:

* **`401 Bad credentials`** — Token expired, revoked, or has zero scopes. Re-issue from Step 2.
* **`403 Resource not accessible by personal access token`** — Token missing a required scope. Compare the failing endpoint against the scope table in Step 2.
* **`403 must use SAML SSO to access this resource`** — Authorize the token for SSO (Step 2, final note).
* **`404 Not Found` on enterprise endpoints** — `GITHUB_ENTERPRISE_SLUG` is wrong or the token's owner is not an Enterprise Owner.
* **`Org Members` finds zero outside collaborators / pending invites** — Frequently legitimate; the org may genuinely have none. Cross-check against `https://github.com/orgs/<org>/people`.

***

## Data Tables

Once the scripts run, the corresponding tables are created in your database. All tables include a `run_at` column for historical tracking. Selected highlights below — see `manifest.json` for the full list.

| Table                           | Source                                             | Key Columns                                                                      |
| ------------------------------- | -------------------------------------------------- | -------------------------------------------------------------------------------- |
| `github_enterprise`             | `/enterprises/{slug}`                              | name, slug, created\_at, billing\_email                                          |
| `github_enterprise_members`     | `/enterprises/{slug}/consumed-licenses`            | login, github\_com\_user, github\_com\_member, license\_type, last\_activity\_at |
| `github_organizations`          | `/enterprises/{slug}/organizations`                | login, id, description, default\_repository\_permission                          |
| `github_org_members`            | `/orgs/{org}/members`                              | org, login, role (admin/member), site\_admin                                     |
| `github_repos`                  | `/orgs/{org}/repos`                                | org, name, private, archived, fork, pushed\_at, size\_kb, default\_branch        |
| `github_repo_branch_protection` | `/repos/{org}/{repo}/branches/{branch}/protection` | required\_status\_checks\_json, require\_pr\_reviews, restrict\_pushes           |
| `github_org_dependabot_alerts`  | `/orgs/{org}/dependabot/alerts`                    | repo, severity, state, dependency, ghsa\_id, created\_at                         |
| `github_copilot_seats`          | `/enterprises/{slug}/copilot/billing/seats`        | login, plan\_type, assignee\_team, created\_at, last\_activity\_at               |
| `github_copilot_usage`          | `/enterprises/{slug}/copilot/usage`                | day, total\_suggestions\_count, total\_acceptances\_count, total\_active\_users  |
| `github_enterprise_audit_log`   | `/enterprises/{slug}/audit-log`                    | action, actor, repo, org, created\_at, raw\_json                                 |

***

## What you can't ingest with this setup

* **Private repo file contents.** ConfigView reads metadata, not source. No commits, no blobs, no diffs.
* **Issue / PR bodies.** Not in scope. Add via custom query if needed.
* **Actions workflow runs / job logs.** Available via API but not wired in — open a feature request if useful.
* **Audit log older than 30 days.** GitHub retains 180 days but the API streams it lazily; the script pulls a rolling 30-day window. Cumulative history accumulates from successive runs in `run_at`.