Demo Integrations Org Data

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:

catalog:
  providers:
    github:
      providerId: 'backstage'
      organization: 'backstage'
      catalogPath: '/catalog-info.yaml'
      filters:
        branch: 'main'
        repository: '.*'
      schedule:
        frequency: { minutes: 30 }
        timeout: { minutes: 3 }

    customProviderId:
      organization: 'new-org'
      catalogPath: '/custom/path/catalog-info.yaml'
      filters:
        branch: 'develop'
        repository: '.*'

    wildcardProviderId:
      organization: 'new-org'
      catalogPath: '/groups/*/*.yaml'
      filters:
        branch: 'develop'
        repository: '.*'

    topicProviderId:
      organization: 'backstage'
      catalogPath: '/catalog-info.yaml'
      filters:
        branch: 'main'
        repository: '.*'

    topicFilterProviderId:
      organization: 'backstage'

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:

yarn --cwd packages/backend add @backstage/plugin-catalog-backend-module-github-org

Next, configure the githubOrg provider in app-config.yaml:

catalog:
  providers:
    githubOrg:
      id: production
      githubUrl: https://github.com
      orgs:
        - organization-1
        - organization-2
        - organization-3
      schedule:
        initialDelay: { seconds: 30 }
        frequency: { hours: 1 }
        timeout: { minutes: 50 }

Then, update your backend index.ts to register the new module:

import { getLogger, loadBackendConfig, startBackend } from '@backstage/backend-common';
import { createRouter } from '@backstage/plugin-catalog-backend';
import authModule from '@backstage/plugin-auth-backend';
import guestProviderModule from '@backstage/plugin-auth-backend-module-guest-provider';
import catalogBackend from '@backstage/plugin-catalog-backend';
import githubModule from '@backstage/plugin-catalog-backend-module-github';
import githubOrgModule from '@backstage/plugin-catalog-backend-module-github-org';
import scaffolderEntityModelModule from '@backstage/plugin-catalog-backend-module-scaffolder-entity-model';

export default async function main() {
  const config = await loadBackendConfig();
  const logger = getLogger();
  const database = await getDatabase();
  const router = await createRouter({ config, logger, database });

  await startBackend({ config, logger, database, router })
    .then(app => {
      app.registerModule(authModule);
      app.registerModule(guestProviderModule);
      app.registerModule(catalogBackend);
      app.registerModule(githubModule);
      app.registerModule(githubOrgModule);
      app.registerModule(scaffolderEntityModelModule);
    });
}

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:

catalog:
  providers:
    githubOrg:
      - id: github
        githubUrl: https://github.com
        orgs:
          - shopping-hub
        schedule:
          initialDelay: { seconds: 30 }
          frequency: { hours: 1 }
          timeout: { minutes: 50 }

    github:
      shoppingHub:
        organization: 'shopping-hub'
        catalogPath: '/catalog-info.yaml'
        filters:
          branch: 'main'
          repository: '.*'
        schedule:
          frequency: { minutes: 20 }
          timeout: { minutes: 2 }

• 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:

Running and Verifying the Import

Apply your changes by restarting Backstage:

yarn dev

If no users or groups appear, it’s likely your GitHub token is missing the required scopes.

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.

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:

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.

Links and References

• Backstage Catalog Providers
• GitHub Provider Plugin
• Backstage Authentication Overview
• GitHub Personal Access Token Scopes