Help Desk

Return to Cortex App

Syncing the Cortex plugin for Backstage

  • Updated

The Cortex plugin for Backstage is set to sync automatically about six times a day. During the sync process, Backstage will map YAML file definitions to the corresponding YAML files in Cortex. 

While the sync will occur by default every four hours, you can edit the cron schedule within the cortex.ts file to adjust the frequency. 

Users can also manually trigger a sync within Backstage by navigating to the Cortex tab in the sidebar. The Sync Entities option is under Settings. 

Default mappings

By default, the sync will implement a number of mappings:

x-cortex-tag comes from the entity reference in Backstage. The Component kind and namespaces with a default name will be omitted from the mapping:

  • Component:namespace/name → namespace/name
  • Group:default/name → Group:name
  • API:namespace/name → API:namespace/name

x-cortex-type maps to the Backstage kind:

  • Component → service
  • Group → team
  • Domain →domain
  • System → domain
  • All others → tagify to x-cortex-type (considered a resource)

x-cortex-owners is taken from any group owners.

  • ownedBy/childOf/partOf/relationships and groups/users are synced into Cortex

x-cortex-children is parsed from spec.owner relations.

title is the name of the entity in Cortex. This is taken from spec.title or metadata.title, else title-cased from metadata.name if missing.

description is taken from spec.description.

x-cortex-dependency is taken from relations.

x-cortex-link is taken from metadata.links:

  • For kind = Location, also taken from spec.targets

x-cortex-groups are the Cortex entity's tags. 

  • Concatenate metadata.tags and if the entity is part of any systems, Cortex will add System:{systemName} as additional Cortex groups.

x-cortex-custom-metadata

  • metadata.labels

x-cortex-git

  • metadata.annotations."github.com/project-slug"
  • metadata.annotations."gitlab.com/project-slug"
  • metadata.annotations."gitlab.com/project-id"

x-cortex-static-analysis.sonarqube

  • metadata.annotations."sonarqube.org/project-key"

x-cortex-sentry

  • metadata.annotations."sentry.io/project-slug"

x-cortex-snyk

  • metadata.annotations."snyk.io/org-name" + metadata.annotations."snyk.io/project-ids"

x-cortex-dashboards.datadog

  • metadata.annotations."datadog.hq.com/dashboard-url"

Custom mappings

In addition to these default mappings, you can use overrides to add your own Cortex tags or override the default mappings.

This can be done by entering Cortex fields in the Backstage manifest spec.

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: artist-lookup
  description: Artist Lookup
spec:
  x-cortex-git:
    github:
    repository: my/repo

Related articles