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 metadataContents: Read: files, commit history, and dependency manifestsAdministration: Read: collaborators, branch protection, and secret scanning and push protection statusActions,Environments,Secrets,Variables(Read, optional): workflows and configuration metadataWebhooks(Read, optional): repository webhooks
Organization permissions:
Members: Read: users, teams, and membershipsPersonal access tokens,Secrets,Variables(Read, optional): inventory and configuration metadataAdministration,Webhooks(Read, optional): organization security settings, verified domains, Actions and Copilot policies, installed GitHub Apps, and organization webhooks
The App only sees the repositories included in the installation. If you limit it to selected repositories, only those are synced.
GHCR ingestion
GitHub App installations cannot support GHCR ingestion. Packages: Read is not an available permission for the Subimage GitHub App installation, and an App installation token cannot be used for GHCR package access. If GHCR ingestion is required, configure the organization through the PAT path with a token that has the read:packages scope. This is optional: without it, the GitHub sync continues normally and only GHCR ingestion is skipped.
Subimage Setup
- Install the Subimage GitHub App from Settings > Integrations.
- Install it in every organization you want Subimage to cover: App installs are organization-scoped.
- Subimage discovers the installed organizations automatically. No personal access token is required for GitHub API inventory for organizations covered by the App. If GHCR ingestion is required, use the PAT path with a token that has the
read:packagesscope; GitHub App installations do not support GHCR ingestion.
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 GHCR ingestion, the token must have read:packages; see the
GitHub module setup guide for the full permission list.
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.