How ownership works

Every entity in Cortex should answer one question: who is responsible for this? Ownership is how Cortex answers it, and almost every other feature depends on that answer. Owners get Scorecard and Initiative notifications, verify entity data, appear on the Engineering homepage, and can be the only people allowed to edit or run Workflows against an entity. Ownership in Cortex works in three layers:

Assignment - Which teams and people are listed as owners of an entity, and where that list comes from.
Propagation - How owners flow from a parent entity, such as a domain, to its children.
Effect - What being an owner lets someone see, receive, and do.

Who can own an entity

An owner is either a team (recommended) or an individual.

Owner type	What it is	In YAML	Stays current when people change roles?
Team owner	A team entity in Cortex, or a group from an identity provider, Git provider, or HR system	`type: group` with a `name` and `provider`	Yes, if the team is synced from an integration
Individual owner	One person, identified by email. They don’t need a Cortex account.	`type: email` with an `email`	No. Deleted users stay listed as owners until you remove them.

x-cortex-owners:
  - type: group
    name: payments-team          # the team's x-cortex-tag
    provider: CORTEX
  - type: group
    name: cortexapps/payments    # a GitHub team, as org/team-slug
    provider: GITHUB
  - type: email
    email: maya.chen@example.com
    description: Escalation contact

For the full list of provider values and the name format each one expects, see Assigning owners to entities.

Teams play two roles in Cortex. A team is an entity in its own catalog, and it’s also the most common owner of other entities. When you open a team’s page, the Entities tab lists what it owns.

Owners, on-call, and contact channels

The Owners block in an entity’s metadata sidebar page shows the following ownership information. If you don’t see the information listed below, the entity doesn’t have it defined yet.

What you see	What it means	Where it’s defined
Teams and people	The entity’s owners	`x-cortex-owners`, the UI, or an integration
Slack or Microsoft Teams channels	Where to reach the owners. Channels don’t count as owners.	`x-cortex-slack`, `x-cortex-microsoft-teams`
On-call	Who’s paged right now, from PagerDuty, Opsgenie, or another on-call tool	`x-cortex-oncall`

Where owners come from

You can combine sources, but each entity should have one source of truth. See Ownership best practices.

Source	How it works	Best for
Ownership tool recommendations	A machine learning model suggests team owners for services and service-like entities, using signals across your catalog, such as code contributions, related services, domain structure, and connected tools. You accept or reject each suggestion.	Filling gaps quickly after import
Cortex UI	Add teams or users in the Owners section of Configure entity	Small catalogs, one-off fixes
Entity YAML	List owners under `x-cortex-owners` and manage them through GitOps	Teams that already manage config as code
Cortex API	Create or patch the entity with its `x-cortex-owners` block	Bulk changes and automation
Identity provider or Git provider sync	Reference a group from Okta, Entra ID, Google, GitHub, GitLab, Bitbucket, or Azure DevOps. Cortex syncs its members daily.	Keeping team membership current
HR or ITSM sync	Import teams and reporting lines from Workday, BambooHR, or ServiceNow	Building the team hierarchy
Cloud tags	Tag AWS or Azure resources with `owner: <team x-cortex-tag>` and enable ownership sync	Cloud resources discovered by Cortex
Inheritance	A domain or other parent passes its owners to children	Entities that should follow their domain

If an entity’s YAML references a Cortex team that doesn’t exist yet, Cortex creates the team and labels it Automatically created by Cortex.

How ownership flows through hierarchies

Cortex has two hierarchies, and they do different things:

Entity hierarchy (domains, and custom relationship types with Ownership enabled) changes who owns the children.
Team hierarchy (parent and child teams) changes what you see. It rolls up views and reports, but it never adds owners to an entity.

Entity hierarchy: inheritance

Each owner on a parent entity has an inheritance mode. If you don’t set one, it’s NONE.

Mode	What children get
`APPEND`	This owner is added to every child, even children that already have owners.
`FALLBACK`	This owner is added to a child only if the child has no other valid owners.
`NONE`	This owner owns the parent only. It’s the default.

In this example, the Payments domain has three owners, each with a different mode:

payments-leads owns the domain only, so neither service lists it.
platform-eng is appended to both services.
payments-team is a fallback, so it appears only on ledger-service, which has no other owners.

Inheritance continues down every level of the hierarchy, so a domain’s APPEND owner also reaches services inside its child domains. If an entity receives the same owner from more than one ancestor, Cortex lists that owner once. The closest ancestor is shown as the source, and the stronger mode wins: APPEND beats FALLBACK, and both beat NONE. To see where an inherited owner came from, open the entity, find Owners in the sidebar, and click the inheritance chain icon next to the owner. Cortex shows the source entity, the relationship type, and the mode. Direct owners don’t have the icon. You can set inheritance in YAML, when you add a domain in the UI, or on a relationship type by turning on Ownership. For details, see Ownership inheritance.

Team hierarchy: roll-up

Teams can have parent and child teams. A parent team doesn’t own what its child teams own, but you can include child teams when you view or report on ownership. Enabling Include child teams (on the Mine tab and Engineering homepage) or Inherited Children (on a team’s Entities tab) adds child teams’ entities to the list. It doesn’t make Engineering an owner of checkout-service, so Engineering members can’t verify it and don’t receive its owner notifications.

Who counts as an owner in each feature

Features check ownership in slightly different ways. Use this table when someone asks why they can see an entity but can’t act on it.

Feature	You count as an owner if
Mine tab and Engineering homepage	You’re listed as an individual owner, or you’re a member of a team that owns the entity. Child teams are optional.
Notifications	You’re an individual owner, or a member of an owning team with notifications enabled. Owners without a Cortex account can be notified if Enable notifications for non-Cortex users is on.
Data verification	You’re a direct member of a team that owns the entity. Inherited owners and parent teams don’t count. If the verification period lists team member roles, you also need one of those roles.
Team ownership entity editing	You’re a member of the owning team and flagged as Editor, or Give edit access to all team members is on. Inherited team owners count. Entities owned only by individuals have no owning team, so nobody gets edit access through this feature.
Workflow run restrictions	You own the target entity and also have edit access to it.
Data Explorer and OpEx Review	Entity owner (Team) groups metrics by the team that owns the entity, including its sub-teams while Include child teams is on (the default). The Team owner filter covers the selected team only. Team (Author) groups metrics by the team of the person who did the work.

What you need before ownership works

Identity mappings connect each Cortex user to their accounts in other tools. Without them, Cortex can’t tell that a GitHub team member is you. Set them up before you rely on:

The Mine tab and Engineering homepage.
The Editor label for team ownership entity editing.
Team metrics in Eng Intelligence.

Ownership tool recommendations work without identity mappings, but they get more accurate as more people are mapped.

Ownership best practices

Set up ownership that stays accurate as your org changes.

Assigning owners to entities

Add owners with recommendations, YAML, or the UI.

Ownership inheritance

Pass owners from domains to their children.

Viewing and managing ownership

Find what you own, find unowned entities, and remove owners.

Cortex

Get Started

Connect data

Standardize

Improve

Streamline

Configure

Resources

How ownership works

Who can own an entity

Owners, on-call, and contact channels

Where owners come from

How ownership flows through hierarchies

Entity hierarchy: inheritance

Team hierarchy: roll-up

Who counts as an owner in each feature

What you need before ownership works

Ownership best practices

Assigning owners to entities

Ownership inheritance

Viewing and managing ownership

​Who can own an entity

​Owners, on-call, and contact channels

​Where owners come from

​How ownership flows through hierarchies

​Entity hierarchy: inheritance

​Team hierarchy: roll-up

​Who counts as an owner in each feature

​What you need before ownership works

​Related pages

Ownership best practices

Assigning owners to entities

Ownership inheritance

Viewing and managing ownership

Who can own an entity

Owners, on-call, and contact channels

Where owners come from

How ownership flows through hierarchies

Entity hierarchy: inheritance

Team hierarchy: roll-up

Who counts as an owner in each feature

What you need before ownership works

Related pages