github

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, branch protection, and secret scanning and push protection status
  • Actions, Environments, Secrets, Variables (Read, optional): workflows and configuration metadata
  • Webhooks (Read, optional): repository webhooks

Organization permissions:

  • Members: Read: users, teams, and memberships
  • Personal access tokens, Secrets, Variables (Read, optional): inventory and configuration metadata
  • Administration, 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.

note

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

  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 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:packages scope; 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.