Skip to main content
In this lesson, you’ll learn how to import organizational data—users and teams—from GitHub into Backstage. By leveraging the githubOrg catalog provider, Backstage automates the creation of User and Group entities based on your organization’s structure.

Overview of Catalog Providers

Backstage supports multiple catalog providers to discover and import entities. Below is a summary of built-in catalog.providers in app-config.yaml:
In this tutorial, we’ll focus on the githubOrg provider to import organizational data (users and teams) from GitHub.

Integrating GitHub Organizational Data

First, install the GitHub Org backend module:
Ensure your workspace is up to date before adding the plugin. This module enables the githubOrg provider in your Backstage backend.
Next, configure the githubOrg provider in app-config.yaml:
Then, update your backend index.ts to register the new module:
The image shows a webpage from Backstage documentation about integrating GitHub organizational data, including sections on permissions and installation. The interface includes a sidebar with navigation links and a dark theme.

Defining GitHub and GitHub Org Providers

You can combine the standard GitHub repository-based provider with the GitHub Org provider to pull both code entities and org data:
  • githubOrg: Imports all users and teams from shopping-hub.
  • github: Discovers catalog-info.yaml in shopping-hub repos to create Component, API, or System entities.
On GitHub, the Shopping Hub organization currently has one owner and several teams:
The image shows a GitHub organization page titled "shopping-hub" under the "People" tab, displaying a single member with owner permissions. A notification suggests having at least two people with the owner role.

Running and Verifying the Import

Apply your changes by restarting Backstage:
The image shows a user interface of a "My Company Catalog" with a list of users, including "guest" and "Jenny Doe," and options for filtering and managing the catalog.
If no users or groups appear, it’s likely your GitHub token is missing the required scopes.
Ensure your GitHub personal access token includes read:org (and optionally read:user). Without these scopes, Backstage cannot retrieve organizational data.
To update your token:
  1. Go to Settings > Developer settings > Personal access tokens in GitHub.
  2. Edit or generate a token with read:org and read:user scopes.
  3. Update the token in Backstage (e.g., via GITHUB_TOKEN env var) and restart.
The image shows a GitHub settings page for editing personal access tokens, with various scopes like "repo" and "workflow" available for selection. A cursor is pointing at the "delete:packages" option.
After adding the correct permissions, Backstage will sync users and teams on the next schedule run. You will then see GitHub members and nested teams as Backstage User and Group entities:
The image shows a dashboard from "My Company Catalog" on Backstage, displaying a list of groups with names, types, and actions available for each group.
By following these steps, you can automate the import of your GitHub organizational structure into Backstage, ensuring your User and Group entities stay up to date.

Watch Video

Practice Lab