The catalog makes use of so called processors to perform all kinds of ingestion
tasks, such as reading raw entity data from a remote source, parsing it,
transforming it, and validating it. These processors are configured under the
url processor is responsible for fetching entity data from files in any
external provider like GitHub, GitLab, Bitbucket, etc. The configuration of this
processor lives under the top-level
integrations key, as it is used by other
parts of Backstage too.
integrations: github: - host: github.com token: $env: GITHUB_TOKEN - host: ghe.example.net apiBaseUrl: https://ghe.example.net/api/v3 rawBaseUrl: https://ghe.example.net/raw token: $env: GHE_TOKEN gitlab: - host: gitlab.com token: $env: GITLAB_TOKEN bitbucket: - host: bitbucket.org username: $env: BITBUCKET_USERNAME appPassword: $env: BITBUCKET_APP_PASSWORD azure: - host: dev.azure.com token: $env: AZURE_TOKEN
Each key under
integrations is a separate configuration for each external
provider. The providers each have their own configuration, so let's look at the
GitHub section as an example.
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
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
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
You need to supply either
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
If you do not supply a public GitHub provider, one will be added automatically,
silently at startup for convenience. So you only have to list it if you want to
supply a token for it - and if you do, you can also leave out the
Static Location Configuration
To enable declarative catalog setups, it is possible to add locations to the
catalog via static configuration. Locations are added to
the catalog under the
catalog.locations key, for example:
catalog: locations: - type: url target: https://github.com/backstage/backstage/blob/master/packages/catalog-model/examples/artist-lookup-component.yaml
The locations added through static configuration can not be removed through the catalog locations API. To remove the locations, you have to remove them from the configuration.
By default the catalog will only allow ingestion of entities with the kind
Location. In order to allow entities of other kinds to
be added, you need to add rules to the catalog. Rules are added either in a
catalog.rules key, or added to statically configured locations.
For example, given the following configuration:
catalog: rules: - allow: [Component, API, Location, Template] locations: - type: url target: https://github.com/org/example/blob/master/org-data.yaml rules: - allow: [Group]
We are able to add entities of kind
Template from any location, and
Group entities from the
which will also be read as statically configured location.
Note that if the
catalog.rules key is present it will replace the default
value, meaning that you need to add rules for the default kinds if you want
those to still be allowed.
The following configuration will reject any kind of entities from being added to the catalog:
catalog: rules: