GitHub
Set up with an AI agent
Using Claude Code, Cursor, Codex CLI, or another coding agent? The subimage-setup:connect-github skill walks the agent through every choice on this page. Paste this into your agent:
Use curl to download, read and follow: https://skills.subimage.io/plugins/subimage-setup/skills/connect-github/SKILL.mdOr install the marketplace once with claude plugin marketplace add subimagesec/skills. Full instructions on Agent Skills.
Purpose
Maps repositories, collaborators, branch protection rules, teams, members, dependency metadata, workflows, and related GitHub configuration from GitHub.com, GitHub Enterprise Cloud, or self-hosted GitHub Enterprise Server into SubImage.
The recommended way to connect GitHub is through the GitHub integration (Settings → Integrations). It uses the SubImage GitHub App with short-lived tokens and automatic org discovery. See the GitHub integration guide for details. The PAT-based configuration below is the fallback for GitHub Enterprise Server and for organizations that cannot use the App.
Secret fields below accept either an AWS Secrets Manager ARN or a value pasted directly into SubImage's managed vault. See Secrets for details.
Authentication Options
Option 1: GitHub App (preferred for GitHub.com and Enterprise Cloud)
Install the SubImage GitHub App in each organization you want to scan. Why this is preferred:
- Short-lived installation tokens instead of long-lived personal tokens
- Connect multiple GitHub organizations by installing the App in each
- Auto-discovered by SubImage: no PAT configuration required
- When the same org is configured both via App and PAT, the App installation wins
The App only sees repositories included in the installation. If the installation is limited to selected repos, only those are synced.
GitHub App installs are org-scoped: install it in every org you want SubImage to cover.
Option 2: Personal Access Tokens (PAT)
Use PAT-based configuration when:
- connecting a self-hosted GitHub Enterprise Server instance
- the SubImage GitHub App is not available
- you need to cover orgs not reachable via App installations
SubImage supports one shared classic PAT across multiple orgs, per-organization PATs (including fine-grained), and a mix of App + PAT auth within the same tenant.
GitHub App Permissions
Grant these to the SubImage GitHub App for full coverage. If you change permissions later, GitHub may require the installation to be re-approved.
Repository permissions
- Metadata: Read: repository discovery and basic metadata
- Contents: Read: repository files, commit history, and dependency manifests
- Administration: Read: collaborator and branch protection coverage
- Actions: Read (optional): workflows and workflow metadata
- Environments: Read (optional): environment configuration
- Secrets: Read (optional): secret metadata only
- Variables: Read (optional): Actions variables
Organization permissions
- Members: Read: users, teams, and memberships
- Personal access tokens: Read (optional): inventory of fine-grained PATs authorized for the org (GitHub App-only; GitHub does not allow PAT-authenticated calls to this endpoint)
- Secrets: Read (optional): secret metadata only
- Variables: Read (optional): organization Actions variables
Configuration Fields
When using the GitHub App
No PAT is required for organizations covered by App installations. github_access_token and github_orgs are optional and only used as fallback for PAT-managed orgs.
| Field | Secret? | Description |
|---|---|---|
github_url |
No | GraphQL API endpoint. Use https://api.github.com/graphql for GitHub.com |
When using PATs
| Field | Secret? | Description |
|---|---|---|
github_access_token |
Yes | Default GitHub PAT |
github_orgs |
No | One or more GitHub organization slugs to scan |
github_url |
No | GraphQL API endpoint, e.g. https://ghe.example.com/api/graphql for GitHub Enterprise |
PAT Types and Scopes
Classic PATs (multi-org)
Minimum scopes:
repo: repository data, commits, workflow filesread:org: teams and membersread:user: user profile detailsuser:email: user email addresses
Fine-grained PATs (per-org)
Recommended permissions:
- Repository → Metadata: Read
- Repository → Contents: Read
- Repository → Administration: Read (collaborator and branch protection)
- Organization → Members: Read
Fine-grained PATs are scoped to a single organization, so multi-org setups require one token per org.
Personal Access Token Inventory
SubImage can ingest personal access tokens authorized against an org so they appear in inventory as GitHubPersonalAccessToken nodes.
- Fine-grained PATs: requires the SubImage GitHub App with
Organization → Personal access tokens: Read. PAT-authenticated configurations cannot reach this endpoint. - Classic PATs: only available through SAML SSO credential authorizations on SAML-enabled organizations. The authenticated user must be an organization owner; classic PAT auth additionally requires
read:org.
When neither path is available, the PAT inventory is empty and the rest of the sync continues normally.
Setup Steps (PAT path)
- Generate a PAT under Settings → Developer settings → Personal access tokens: Tokens (classic) for a shared multi-org token, Fine-grained tokens for single-org or per-org setups.
- In SubImage, set:
github_access_token: the token (or its AWS Secret ARN)github_orgs: one entry per organization sluggithub_url: override for GitHub Enterprise Server- optionally configure per-org token ARNs where needed
- Save the module.
Multi-Organization Support
- Via GitHub App: install the App in each target org; SubImage auto-discovers and syncs each one. Preferred for GitHub.com and Enterprise Cloud.
- Via PAT: list orgs in
github_orgs. Use one shared classic PAT, or provide per-org tokens where needed. Fine-grained PATs always require one token per org.
GitHub Enterprise Server
Use the PAT path and set github_url to your enterprise GraphQL endpoint, e.g. https://ghe.example.com/api/graphql.