This section lists a number of well known annotations, that have defined semantics. They can be attached to catalog entities and consumed by plugins as needed.
This is a (non-exhaustive) list of annotations that are known to be in active use.
# Example: metadata: annotations: backstage.io/managed-by-location: github:http://github.com/spotify/backstage/catalog-info.yaml
The value of this annotation is a so called location reference string, that
points to the source from which the entity was originally fetched. This
annotation is added automatically by the catalog as it fetches the data from a
registered location, and is not meant to normally be written by humans. The
annotation may point to any type of generic location that the catalog supports,
so it cannot be relied on to always be specifically of type
github, nor that
it even represents a single file. Note also that a single location can be the
source of many entities, so it represents a many-to-one relationship.
The format of the value is
<type>:<target>. Note that the target may also
contain colons, so it is not advisable to naively split the value on
expecting a two-item array out of it. The format of the target part is
type-dependent and could conceivably even be an empty string, but the separator
colon is always present.
# Example apiVersion: backstage.io/v1alpha1 kind: API metadata: name: petstore annotations: backstage.io/definition-at-location: 'url:https://petstore.swagger.io/v2/swagger.json' spec: type: openapi
This annotation allows to fetch an API definition from another location, instead of wrapping the API definition inside the definition field. This allows to easitly consume existing API definition. The definition is fetched during ingestion by a processor and included in the entity. It is updated on every refresh. The annotation contains a location reference string that contains the location processor type and the target.
# Example: metadata: annotations: backstage.io/techdocs-ref: github:https://github.com/spotify/backstage.git
The value of this annotation is a location reference string (see above). If this annotation is specified, it is expected to point to a repository that the TechDocs system can read and generate docs from.
# Example: metadata: annotations: jenkins.io/github-folder: folder-name/job-name
The value of this annotation is the path to a job on Jenkins, that builds this entity.
Specifying this annotation may enable Jenkins related features in Backstage for that entity.
# Example: metadata: annotations: github.com/project-slug: spotify/backstage
The value of this annotation is the so-called slug that identifies a project on
GitHub that is related to this entity. It is on the format
<organization>/<project>, and is the same as can be seen in the URL location
bar of the browser when viewing that project.
Specifying this annotation will enable GitHub related features in Backstage for that entity.
# Example: metadata: annotations: sentry.io/project-slug: pump-station
The value of this annotation is the so-called slug (or alternatively, the ID) of a Sentry project within your organization. The organization slug is currently not configurable on a per-entity basis, but is assumed to be the same for all entities in the catalog.
Specifying this annotation may enable Sentry related features in Backstage for that entity.
# Example: metadata: annotations: rollbar.com/project-slug: spotify/pump-station
The value of this annotation is the so-called slug (or alternatively, the ID) of
a Rollbar project within your organization. The value can
be the format of
[organization]/[project-slug] or just
the organization slug is omitted the
app-config.yaml will be used as a
rollbar.organization followed by
Specifying this annotation may enable Rollbar related features in Backstage for that entity.
The following annotations are deprecated, and only listed here to aid in migrating away from them.
This annotation was used for a while to enable the GitHub Actions feature. This is now instead using the github.com/project-slug annotation, with the same value format.