> ## Documentation Index
> Fetch the complete documentation index at: https://backstage.spotify.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect GitHub and populate the catalog

> Configure a GitHub App for Portal and ingest repositories, users, and groups for Xirp and Workspaces.

Portal uses an organization-level GitHub App to discover repositories and populate the Software Catalog. Xirp uses catalog source locations to find the repository behind a component when a session starts from Portal.

<Note>
  This is an administrator task. You need administrative access to both Portal
  and the GitHub organization.
</Note>

## Before you start

Collect:

* The GitHub organization name
* A GitHub organization administrator who can install an app
* Portal administrator access
* A decision about whether the app can access all repositories or selected repositories

During the beta, GitHub onboarding supports organization-level app installations. User-owned GitHub Apps and automatic monorepo onboarding are not supported.

## Configure the GitHub App

1. In Portal, open the setup or administration flow for GitHub.
2. Create the GitHub App using the values and permissions Portal provides.
3. Install the app on the organization.
4. Choose the repositories Portal may read.
5. Copy the App ID, Client ID, client secret, and private key into Portal's secure configuration flow.
6. Save the integration and wait for Portal to restart if prompted.

<img src="https://mintcdn.com/spotify-89f50c35/_WMpAEP2WBxIObwy/portal/assets/github-app-installation.png?fit=max&auto=format&n=_WMpAEP2WBxIObwy&q=85&s=a5ae58f68068d1b067f01eebebb30db8" alt="GitHub App installation and repository selection" width="1077" height="769" data-path="portal/assets/github-app-installation.png" />

The complete permission list and credential fields are maintained in the [Portal GitHub authentication guide](/docs/portal/guides/auth/github). Follow that guide rather than inventing additional permissions.

<Warning>
  Treat the private key and client secret as credentials. Do not paste them into
  source control, chat, tickets, or Xirp prompts.
</Warning>

## Automatic catalog ingestion

After you create and connect the GitHub App, Portal automatically begins ingesting the repositories that the app can access. It also makes imported users and groups available for catalog and Workspace membership workflows. No separate catalog-provider setup is required.

Review the imported repositories in the Software Catalog after the initial synchronization completes.

<img src="https://mintcdn.com/spotify-89f50c35/_WMpAEP2WBxIObwy/portal/assets/github-auth/github_integration_image_three_blur.png?fit=max&auto=format&n=_WMpAEP2WBxIObwy&q=85&s=e3caddbc44cb933d38e2a6743fdca612" alt="GitHub authentication configuration in Portal" width="1930" height="842" data-path="portal/assets/github-auth/github_integration_image_three_blur.png" />

For integration failures, use the [GitHub integration troubleshooting guide](/docs/portal/troubleshooting/github-integration).