Skip to main content
Version: v2 (preview)

GitHub Auth & Integrations

GitHub is one of the most common integrations in VeeCode DevPortal (Backstage). V2 activates GitHub capabilities through two composable presets: github for SCM/backend operations and github-auth for OAuth sign-in and org sync.

Overview​

VeeCode DevPortal interacts with GitHub in two distinct ways:

  • Authentication / identity: How users sign in to DevPortal using their GitHub accounts (via OAuth App). Activated by the github-auth preset.
  • Backend integrations: How DevPortal's backend services (catalog, scaffolder, plugins) access GitHub APIs to fetch data and perform actions. Activated by the github preset.

These two aspects are configured as separate presets and can be combined freely. For a full GitHub stack, use both:

VEECODE_PRESETS=recommended,github,github-auth

For GitHub as SCM with a different identity provider (e.g., Keycloak), omit github-auth and add your identity preset instead.

Why separate presets?​

Separating SCM from identity lets you:

  • Use GitHub repositories but sign in via Keycloak, LDAP, or Azure AD.
  • Use GitHub OAuth as your identity provider while storing code in GitLab or Azure DevOps.
  • Grant the SCM PAT only repo/read:org scopes without conflating them with OAuth consent scopes shown to users.

github preset — SCM and backend​

The github preset wires:

  • The GitHub integration token for catalog/scaffolder/backend plugin calls (GITHUB_PAT)
  • The GitHub catalog provider for automated catalog-info.yaml discovery from your org's repos (GITHUB_ORG)
  • The GitHub Actions UI tab on entity pages

Required environment variables:

VariableDescription
GITHUB_PATPersonal Access Token with repo and read:org scopes
GITHUB_ORGGitHub organization to scan for catalog-info.yaml files

github-auth preset — OAuth sign-in and org sync​

The github-auth preset wires:

  • GitHub OAuth sign-in for users
  • The githubOrg catalog provider, which syncs org members and teams as User/Group entities
  • Disables the guest fallback so the login screen presents GitHub OAuth

Required environment variables:

VariableDescription
GITHUB_PATPersonal Access Token with read:org scope (used by the githubOrg catalog provider)
GITHUB_ORGGitHub organization whose members/teams sync into the catalog
GITHUB_AUTH_CLIENT_IDOAuth App client ID from GitHub Developer Settings
GITHUB_AUTH_CLIENT_SECRETOAuth App client secret
note

github-auth belongs to the exclusive identity group. Only one identity preset can be active per deployment.

Decision tree​

This is a decision tree to help you understand which credential is used in which context:

How to read this​

  • User login path (github-auth preset): always OAuth via a GitHub OAuth App. Users get an OAuth token with the requested scopes.
  • Backend path (github preset): uses the GITHUB_PAT for catalog discovery, scaffolder actions, and plugin API calls. If a GitHub App is configured in an app-config.local.yaml overlay, Backstage prefers App installation tokens and falls back to the PAT.

Composition examples​

Full GitHub stack​

VEECODE_PRESETS=recommended,github,github-auth
GITHUB_PAT=ghp_xxxx
GITHUB_ORG=my-org
GITHUB_AUTH_CLIENT_ID=Iv1.abcdef0123456789
GITHUB_AUTH_CLIENT_SECRET=github-oauth-secret

GitHub as SCM + Keycloak as identity​

VEECODE_PRESETS=recommended,github,keycloak
GITHUB_PAT=ghp_xxxx
GITHUB_ORG=my-org
KEYCLOAK_BASE_URL=https://keycloak.example.com/auth
KEYCLOAK_REALM=my-realm
KEYCLOAK_CLIENT_ID=devportal
KEYCLOAK_CLIENT_SECRET=xxx
AUTH_SESSION_SECRET=xxx

GitHub as identity only (no GitHub repos)​

VEECODE_PRESETS=recommended,github-auth
GITHUB_PAT=ghp_xxxx
GITHUB_ORG=my-org
GITHUB_AUTH_CLIENT_ID=Iv1.abcdef0123456789
GITHUB_AUTH_CLIENT_SECRET=github-oauth-secret