Catalog Configuration
Processors
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
catalog.processors
key.
Processor: url
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 isgithub.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 athttps://api.<host>
orhttps://<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 athttps://api.<host>
orhttps://<host>/api/v3
.
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.
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 apiBaseUrl
and rawBaseUrl
fields.
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.
Catalog Rules
By default the catalog will only allow ingestion of entities with the kind
Component
, API
and 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
separate 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 Component
, API
, Location
, or
Template
from any location, and Group
entities from the org-data.yaml
,
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: []