目录实体上的常见注解(annotation)

本节列出了一些常见的annotations 注解它们可以附加到目录实体上，并由插件根据需要使用。

注解

这是一份已知正在使用的注解列表(并非详尽无遗)。

backstage.io/managed-by-location

# Example:
metadata:
  annotations:
    backstage.io/managed-by-location: url:http://github.com/backstage/backstage/blob/master/catalog-info.yaml

该注解的值是一个所谓的位置引用字符串，指向最初获取实体的来源。 该注解是目录从注册位置获取数据时自动添加的，通常不是由人工编写的。 该注解可以指向目录支持的任何类型的通用位置，因此不能依赖于它始终是特定类型的注解。url还要注意的是，一个位置可以是许多实体的来源，因此它代表的是多对一的关系。

数值格式为<type>:<target>请注意，目标值也可能包含冒号，因此不建议简单地在:目标部分的格式取决于类型，甚至可以是空字符串，但分隔符冒号总是存在的。

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

该注解的值是一个位置引用字符串(见上文)。 它指向一个位置，该位置的注册导致了实体的创建。 在大多数情况下，该注解的值为backstage.io/managed-by-location和backstage.io/managed-by-origin-location将相等。 如果原始位置委托给另一个位置，它们将不同。 常见的情况是，一个位置被注册为bootstrap:bootstrap这意味着它是app-config.yaml的Backstage装置。

backstage.io/orphan

该注解要么不存在，要么存在，但有一个确切的字符串价值"true"对于那些没有注册位置或配置位置来保持 "活动"/"存活 "的实体，目录本身会注入注解，作为其处理循环的一部分。

例如，假设用户首先注册了一个位置 URL，指向一个Location种实体，而这种实体又指两个Component最终结果是目录中包含了这三个实体。 现在假设用户编辑了原始的Location实体，以便仅引用Component这将有意不是相通Component相反，它获得了孤儿标记注解，以清楚地表明，如果需要，用户必须采取行动才能完全删除它。

# Example:
metadata:
  annotations:
    backstage.io/orphan: 'true'

backstage.io/techdocs-ref

# Example:
metadata:
  annotations:
    backstage.io/techdocs-ref: dir:.

该注解的值可告知在存储 TechDocs 源内容的目的是为了读取它，并从中生成文档。 通常，它被写成一个路径，相对于catalog-info.yaml本身，其中相关的mkdocs.yml文件。

在目录实体的文档不与实体的源代码同时存在的特殊情况下，该注解的值可以指向绝对 URL，例如，与上述位置引用字符串格式相匹配：url:https://github.com/backstage/backstage/tree/master

backstage.io/techdocs-entity

# Example:
metadata:
  annotations:
    backstage.io/techdocs-entity: component:default/example

此注解的值将告知拥有 TechDocs 的外部实体。 这样，您就可以从单一来源引用 TechDocs，而无需在 TechDocs 页面中重复 TechDocs 或需要多次构建相同的文档。

这适用于拥有复杂系统的情况，这些系统共享一个 repo，也可能共享一个 TechDoc 位置。

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

这些注解允许自定义目录页面的链接。 查看 URL 应指向治理该实体的规范元数据 YAML。 编辑 URL 应指向元数据的源文件。 在上面的例子中、my-org在 monorepo 中从 Jsonnet 文件生成目录数据，因此需要更改查看和编辑链接。

backstage.io/source-location

# Example:
metadata:
  annotations:
    backstage.io/source-location: url:https://github.com/my-org/my-service/

ALocation指向实体源代码的引用(通常是一个Component如果目录文件不是从源代码库中获取的，那么URL 就很有用。 如果URL 指向一个文件夹，那么后缀必须是'/'以确保相对路径解析的一致性。

jenkins.io/job-full-name

# Example:
metadata:
  annotations:
    jenkins.io/job-full-name: folder-name/job-name

此注解的值是指向 Jenkins 上构建此实体的作业的路径。

值的格式可以是[folder-path]或[instanceName]:[folder-path]如果在app-config.yaml

指定此注解可在 Backstage 中为该实体启用 Jenkins 相关功能。

github.com/project-slug

# Example:
metadata:
  annotations:
    github.com/project-slug: backstage/backstage

该注解的值是所谓的 slug，用于标识存储库在GitHub(格式为<organization or owner>/<repository>与查看该资源库时在浏览器 URL 位置栏中看到的位置相同。

指定此注解后，该实体的 GitHub 相关功能将在 Backstage 中启用。

github.com/team-slug

# Example:
metadata:
  annotations:
    github.com/team-slug: backstage/maintainers

该注解的值是所谓的标头，用于在GitHub(格式为<organization>/<team>与查看该团队时在浏览器 URL 位置栏中看到的位置相同。

该注解可用于集团实体以说明它源自 GitHub 上的那个团队。

github.com/user-login

# Example:
metadata:
  annotations:
    github.com/user-login: freben

该注解的值是所谓的登录信息，用于识别用户在GitHub(格式为<username>与查看该用户时在浏览器 URL 定位栏中看到的内容相同。

该注解可用于用户实体以注明它来自 GitHub 上的该用户。

gocd.org/pipelines

# Example:
metadata:
  annotations:
    gocd.org/pipelines: backstage,backstage-pr,backstage-builder

此注解的值是以逗号分隔的 GoCD 管道名称列表，用于获取 CI/CD 信息。

管道名称通常在gocd.yml文件中的管道定义。

指定此注解将在Backstage为该实体启用 GoCD 相关功能。

periskop.io/service-name

# Example:
metadata:
  annotations:
    periskop.io/service-name: pump-station

此注解的值是给定实体的 periskop 项目名称。

指定此注解将使佩里斯科普如果安装了 periskop 插件，该实体可在Backstage使用相关功能。

sentry.io/project-slug

# Example:
metadata:
  annotations:
    sentry.io/project-slug: backstage/pump-station

该注解的值就是所谓的标头(或 ID)。哨兵该值的格式可以是[organization]/[project-slug]或者只是[project-slug]如果省略了组织标识符，则app-config.yaml将作为后备 (sentry.organization).

指定此注解可在 Backstage 中为该实体启用哨兵相关功能。

rollbar.com/project-slug

# Example:
metadata:
  annotations:
    rollbar.com/project-slug: backstage/pump-station

该注解的值就是所谓的标头(或 ID)。滚杠该值的格式可以是[organization]/[project-slug]或者只是[project-slug]如果省略了组织标识符，则app-config.yaml将作为后备 (rollbar.organization随后是organization.name).

指定此注解可启用该实体在 Backstage 中的滚动条相关功能。

circleci.com/project-slug

# Example:
metadata:
  annotations:
    circleci.com/project-slug: github/spotify/pump-station

该注解的值就是所谓的标头(或 ID)。CircleCI该值的格式可以是[source-control-manager]/[organization]/[project-slug]或者只是[organization]/[project-slug]当[source-control-manager]省略、bitbucket将作为备用。

指定此注解将使Backstage的 CI/CD 功能显示来自 CircleCI 的该实体的数据。

同时提供github.com/project-slug和circleci.com/project-slug注解可能会造成问题，因为两者都可能用于 CI/CD 功能。

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

这些注解的值是在从 LDAP 采集实体时发现的相应属性。 并非所有属性都会出现，这取决于服务器在采集时提供了哪些属性。

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

这些注解的值是在从 Microsoft Graph API 摄取实体时发现的相应属性，但并非所有属性都存在，这取决于服务器在摄取时显示了哪些属性。

sonarqube.org/project-key

# Example:
metadata:
  annotations:
    sonarqube.org/project-key: pump-station

该注解的值是一个SonarQube或云声纳项目。

指定此注解可在 Backstage 中为该实体启用 SonarQube 相关功能。

backstage.io/code-coverage

# Example:
metadata:
  annotations:
    backstage.io/code-coverage: scm-only

该注解的值控制代码覆盖Backstage插件。 如果设置为scm-only，插件将只考虑存储在源控制中的文件(例如忽略生成的代码)。 如果设置为enabled如果覆盖范围报告涉及的所有文件都将被考虑在内。

vault.io/secrets-path

# Example:
metadata:
  annotations:
    vault.io/secrets-path: test/backstage

此注解的值包含 Vault 中实体Secret的路径。 如果在使用 Vault 插件时不存在，则会显示一条信息，让用户知道在catalog-info.yaml.

过时的注解

以下注解已被弃用，在此列出只是为了帮助迁移时避免使用这些注解。

backstage.io/github-actions-id

该注解曾一度用于启用 GitHub 动作功能，现在则使用github.com/project-slug注解，数值格式相同。

backstage.io/definition-at-location

该注解允许从其他位置加载 API 定义。 使用代谢而不是

jenkins.io/github 文件夹

使用jenkins.io/job-full-name而不是

链接

• 描述符格式：注解