GitHub

Connect GitHub from Settings > Integrations to let SubImage sync repositories, teams, members, branch protection, and dependency metadata without managing long-lived personal access tokens.

What SubImage Does

SubImage connects through the SubImage GitHub App. The App issues short-lived installation tokens that refresh automatically, and SubImage auto-discovers the organizations where the App is installed, so no token configuration is required. When the same organization is reachable through both the App and a personal access token, the App installation wins.

The GitHub sync module still controls what SubImage ingests. The App covers GitHub.com and GitHub Enterprise Cloud; GitHub Enterprise Server uses the personal access token fallback below.

App Permissions

When you install the SubImage GitHub App, grant these permissions for full coverage. Changing permissions later may require GitHub to re-approve the installation.

Repository permissions:

• Metadata: Read: repository discovery and basic metadata
• Contents: Read: files, commit history, and dependency manifests
• Administration: Read: collaborators and branch protection
• Actions, Environments, Secrets, Variables (Read, optional): workflows and configuration metadata

Organization permissions:

• Members: Read: users, teams, and memberships
• Personal access tokens, Secrets, Variables (Read, optional): inventory and configuration metadata

The App only sees the repositories included in the installation. If you limit it to selected repositories, only those are synced.

SubImage Setup

1. Install the SubImage GitHub App from Settings > Integrations.
2. Install it in every organization you want SubImage to cover: App installs are organization-scoped.
3. SubImage discovers the installed organizations automatically. No personal access token is required for organizations covered by the App.

Personal Access Token Fallback

Use a GitHub personal access token instead of the App when:

• you are connecting a self-hosted GitHub Enterprise Server instance
• the SubImage GitHub App is not available
• you need to cover organizations not reachable through App installations

SubImage supports a shared classic token across organizations, per-organization tokens (including fine-grained), and a mix of App and token auth in the same tenant. For token-based setup details, see the GitHub module setup guide.

Troubleshooting

If SubImage cannot sync GitHub after installation, confirm the App is installed in the organization and that its installation includes the repositories you expect.

If a personal access token is rejected, confirm its scopes and, for the App, reinstall GitHub from Settings > Integrations so GitHub issues a fresh installation grant.