Well-known Annotations on Catalog Entities
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.
Annotations
This is a (non-exhaustive) list of annotations that are known to be in active use.
backstage.io/managed-by-location
# Example:
metadata:
annotations:
backstage.io/managed-by-location: url:http://github.com/backstage/backstage/blob/master/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 url, 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 : and
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.
backstage.io/managed-by-origin-location
# Example:
metadata:
annotations:
backstage.io/managed-by-origin-location: url:http://github.com/backstage/backstage/blob/master/catalog-info.yaml
The value of this annotation is a location reference string (see above). It
points to the location, whose registration lead to the creation of the entity.
In most cases, the backstage.io/managed-by-location and
backstage.io/managed-by-origin-location will be equal. They will be different
if the original location delegates to another location. A common case is, that a
location is registered as bootstrap:bootstrap which means that it is part of
the app-config.yaml of a Backstage installation.
backstage.io/orphan
This annotation is either absent, or present with the exact string value
"true". It should never be added manually. Instead, the catalog itself injects
the annotation as part of its processing loops, on entities that are found to
have no registered locations or config locations that keep them "active" /
"alive".
For example, suppose that the user first registers a location URL pointing to a
Location kind entity, which in turn refers to two Component kind entities in
two other files nearby. The end result is that the catalog contains those three
entities. Now suppose that the user edits the original Location entity to only
refer to the first of the Component kind entities. This will intentionally
not lead to the other Component entity to be removed from the catalog (for
safety reasons). Instead, it gains this orphan marker annotation, to make it
clear that user action is required to completely remove it, if desired.
# Example:
metadata:
annotations:
backstage.io/orphan: 'true'
backstage.io/techdocs-ref
# Example:
metadata:
annotations:
backstage.io/techdocs-ref: dir:.
The value of this annotation informs where TechDocs source content is stored
so that it can be read and docs can be generated from it. Most commonly, it's
written as a path, relative to the location of the catalog-info.yaml itself,
where the associated mkdocs.yml file can be found.
In unusual situations where the documentation for a catalog entity does not live
alongside the entity's source code, the value of this annotation can point to an
absolute URL, matching the location reference string format outlined above, for
example: url:https://github.com/backstage/backstage/tree/master
backstage.io/techdocs-entity
# Example:
metadata:
annotations:
backstage.io/techdocs-entity: component:default/example
The value of this annotation informs of an external entity that owns the TechDocs. This allows you to reference TechDocs from a single source without either duplicating the TechDocs in the TechDocs page or needing multiple builds of the same docs.
This is for situations where you have complex systems where they share a single repo, and likely a single TechDoc location.
backstage.io/view-url, backstage.io/edit-url
# Example:
metadata:
annotations:
backstage.io/view-url: https://some.website/catalog-info.yaml
backstage.io/edit-url: https://github.com/my-org/catalog/edit/master/my-service.jsonnet
These annotations allow customizing links from the catalog pages. The view URL
should point to the canonical metadata YAML that governs this entity. The edit
URL should point to the source file for the metadata. In the example above,
my-org generates its catalog data from Jsonnet files in a monorepo, so the
view and edit links need changing.
backstage.io/source-location
# Example:
metadata:
annotations:
backstage.io/source-location: url:https://github.com/my-org/my-service/
A Location reference that points to the source code of the entity (typically a
Component). Useful when catalog files do not get ingested from the source code
repository itself. If the URL points to a folder, it is important that it is
suffixed with a '/' in order for relative path resolution to work
consistently.
backstage.io/source-template
# Example:
metadata:
annotations:
backstage.io/source-template: template:default/create-react-app-template
Represents the entity ref of the Scaffolder template that was originally used to create the given entity. Useful to power "create something similar" experiences, as well as to track adherence to software standards across the Catalog.
Note that this value is only automatically added to an entity when the
catalog:write action is used to create the catalog-info.yaml file. It is
otherwise the template author's responsibility to ensure that any entity
definition included as part of the template contains this annotation.
jenkins.io/job-full-name
# Example:
metadata:
annotations:
jenkins.io/job-full-name: folder-name/job-name
The value of this annotation is the path to a job on Jenkins, that builds this entity.
The value can be the format of just [folder-path] or
[instanceName]:[folder-path], if multiple instances are configured in
app-config.yaml
Specifying this annotation may enable Jenkins related features in Backstage for that entity.
github.com/project-slug
# Example:
metadata:
annotations:
github.com/project-slug: backstage/backstage
The value of this annotation is the so-called slug that identifies a repository on
GitHub (either the public one, or a private GitHub
Enterprise installation) that is related to this entity. It is on the format
<organization or owner>/<repository>, and is the same as can be seen in the URL location
bar of the browser when viewing that repository.
Specifying this annotation will enable GitHub related features in Backstage for that entity.
github.com/team-slug
# Example:
metadata:
annotations:
github.com/team-slug: backstage/maintainers
The value of this annotation is the so-called slug that identifies a team on
GitHub (either the public one, or a private GitHub
Enterprise installation) that is related to this entity. It is on the format
<organization>/<team>, and is the same as can be seen in the URL location bar
of the browser when viewing that team.
This annotation can be used on a Group entity to note that it originated from that team on GitHub.
github.com/user-login
# Example:
metadata:
annotations:
github.com/user-login: freben
The value of this annotation is the so-called login that identifies a user on
GitHub (either the public one, or a private GitHub
Enterprise installation) that is related to this entity. It is on the format
<username>, and is the same as can be seen in the URL location bar of the
browser when viewing that user.
This annotation can be used on a User entity to note that it originated from that user on GitHub.
gocd.org/pipelines
# Example:
metadata:
annotations:
gocd.org/pipelines: backstage,backstage-pr,backstage-builder
The value of this annotation is a comma-separated list of the GoCD pipeline names to fetch CI/CD information for.
The pipeline name is usually defined in the gocd.yml file for the pipeline
definition.
Specifying this annotation will enable GoCD related features in Backstage for that entity.
periskop.io/service-name
# Example:
metadata:
annotations:
periskop.io/service-name: pump-station
The value of this annotation is the periskop project name for the given entity.
Specifying this annotation will enable Periskop related features in Backstage for that entity if the periskop plugin is installed.
sentry.io/project-slug
# Example:
metadata:
annotations:
sentry.io/project-slug: backstage/pump-station
The value of this annotation is the so-called slug (or alternatively, the ID) of
a Sentry project within your organization. The value can
be the format of [organization]/[project-slug] or just [project-slug]. When
the organization slug is omitted the app-config.yaml will be used as a
fallback (sentry.organization).
Specifying this annotation may enable Sentry related features in Backstage for that entity.
rollbar.com/project-slug
# Example:
metadata:
annotations:
rollbar.com/project-slug: backstage/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 [project-slug]. When
the organization slug is omitted the app-config.yaml will be used as a
fallback (rollbar.organization followed by organization.name).
Specifying this annotation may enable Rollbar related features in Backstage for that entity.
circleci.com/project-slug
# Example:
metadata:
annotations:
circleci.com/project-slug: github/spotify/pump-station
The value of this annotation is the so-called slug (or alternatively, the ID) of
a CircleCI project within your organization. The value
can be the format of [source-control-manager]/[organization]/[project-slug] or
just [organization]/[project-slug]. When the [source-control-manager] slug
is omitted, bitbucket will be used as a fallback.
Specifying this annotation will cause the CI/CD features in Backstage to display data from CircleCI for that entity.
Providing both the github.com/project-slug and circleci.com/project-slug
annotations can cause problems as both may be used for CI/CD features.
backstage.io/ldap-rdn, backstage.io/ldap-uuid, backstage.io/ldap-dn
# Example:
metadata:
annotations:
backstage.io/ldap-rdn: my-team
backstage.io/ldap-uuid: c57e8ba2-6cc4-1039-9ebc-d5f241a7ca21
backstage.io/ldap-dn: cn=my-team,ou=access,ou=groups,ou=spotify,dc=spotify,dc=net
The value of these annotations are the corresponding attributes that were found when ingesting the entity from LDAP. Not all of them may be present, depending on what attributes that the server presented at ingestion time.
graph.microsoft.com/tenant-id, graph.microsoft.com/group-id, graph.microsoft.com/user-id
# Example:
metadata:
annotations:
graph.microsoft.com/tenant-id: 6902611b-ffc1-463f-8af3-4d5285dc057b
graph.microsoft.com/group-id: c57e8ba2-6cc4-1039-9ebc-d5f241a7ca21
graph.microsoft.com/user-id: 2de244b5-104b-4e8f-a3b8-dce3c31e54b6
The value of these annotations are the corresponding attributes that were found when ingesting the entity from the Microsoft Graph API. Not all of them may be present, depending on what attributes that the server presented at ingestion time.
sonarqube.org/project-key
# Example:
metadata:
annotations:
sonarqube.org/project-key: pump-station
The value of this annotation is the project key of a SonarQube or SonarCloud project within your organization.
Specifying this annotation may enable SonarQube related features in Backstage for that entity.
backstage.io/code-coverage
# Example:
metadata:
annotations:
backstage.io/code-coverage: scm-only
The value of this annotation controls the code-coverage backstage plugin. If set
to scm-only, the plugin will only take into account files stored in source
control (e.g. ignoring generated code). If set to enabled, all files covered
by a coverage report will be taken into account.
vault.io/secrets-path
# Example:
metadata:
annotations:
vault.io/secrets-path: test/backstage
The value of this annotation contains the path to the secrets of the entity in
Vault. If not present when the Vault plugin is in use, a message will be shown
instead, letting the user know what is missing in the catalog-info.yaml.
Deprecated Annotations
The following annotations are deprecated, and only listed here to aid in migrating away from them.
backstage.io/github-actions-id
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.
backstage.io/definition-at-location
This annotation allowed to load the API definition from another location. Use substitution instead.
jenkins.io/github-folder
Use the jenkins.io/job-full-name instead.