Skip to main content

GitHub Locations

The GitHub integration supports loading catalog entities from github.com or GitHub Enterprise. Entities can be added to static catalog configuration, registered with the catalog-import plugin, or discovered from a GitHub organization. Users and Groups can also be loaded from an organization.

Configuration​

To use this integration, add configuration to your root app-config.yaml:

integrations:
  github:
    - host: github.com
      token: ${GITHUB_TOKEN}
    - host: ghe.example.net
      apiBaseUrl: https://ghe.example.net/api/v3
      rawBaseUrl: https://ghe.example.net/raw
      token: ${GHE_TOKEN}
Note

A public GitHub provider is added automatically at startup for convenience, so you only need to list it if you want to supply a token.

Directly under the github key is a list of provider configurations, where you can list the various GitHub-compatible providers you want to be able to fetch data from. Each entry is a structure with up to four elements:

  • host (optional): The host of the location target that you want to match on. The default host is github.com.
  • token (optional): An authentication token as expected by GitHub. If supplied, it will be passed along with all calls to this provider, both API and raw. If it is not supplied, anonymous access will be used.
  • apiBaseUrl (optional): If you want to communicate using the APIv3 method with this provider, specify the base URL for its endpoint here, with no trailing slash. Specifically when the target is GitHub, you can leave it out to be inferred automatically. For a GitHub Enterprise installation, it is commonly at https://api.<host> or https://<host>/api/v3.
  • rawBaseUrl (optional): If you want to communicate using the raw HTTP method with this provider, specify the base URL for its endpoint here, with no trailing slash. Specifically when the target is public GitHub, you can leave it out to be inferred automatically. For a GitHub Enterprise installation, it is commonly at https://<host>/raw.

You need to supply either apiBaseUrl or rawBaseUrl or both (except for public GitHub, for which we can infer them). The apiBaseUrl will always be preferred over the other if a token is given, otherwise rawBaseUrl will be preferred.

Token scopes​

When creating a personal access token on GitHub, you must select scopes to define the level of access for the token. The scopes required vary depending on your use of the integration:

  • Reading software components:
    • repo
  • Reading organization data:
    • read:org
    • read:user
    • user:email
  • Publishing software templates:
    • repo
    • workflow (if templates include GitHub workflows)

Authentication with GitHub Apps​

Alternatively for GitHub organizations, Backstage can use GitHub Apps for backend authentication. This has higher rate limits, and a clearer authorization model. See github-apps for how to set this up.