> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cortex.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Ownership best practices

> Set up entity ownership in Cortex that stays accurate as people and teams change

Ownership is only useful if it's right. A stale owner means notifications go to someone who left, verifications stall, and Scorecard failures land on nobody's homepage. These practices help you set up ownership once and keep it current with little manual work.

If you're new to ownership in Cortex, start with [How ownership works](/ingesting-data-into-cortex/entities-overview/entities/ownership).

## Quick checklist

* [ ] Every entity is owned by at least one team.
* [ ] Teams are synced from an identity provider, Git provider, or HR system.
* [ ] Identity mappings are configured for your Git, on-call, and chat tools.
* [ ] Each entity type has one source of truth for owners: the UI or GitOps.
* [ ] Domains use inheritance on purpose, not by default.
* [ ] A Scorecard flags entities without owners.
* [ ] A recurring data verification period asks owners to confirm their entities.

## Assign teams, not people

Make a team the owner of every entity. Add an individual only as an extra contact.

* **Teams survive turnover.** When someone leaves a synced team, Cortex removes them from the team at the next sync. The entity keeps its owner.
* **Individual owners don't update.** Deleting a user from Cortex doesn't remove their email from owner fields. You have to find and replace them.
* **Most features act on teams.** Team notifications, ownership-based editing, data verification roles, and team metrics in Eng Intelligence all work through team membership.

<Tip>
  Use individual owners for people outside your team structure, such as a security reviewer or a vendor contact. Add a `description` so others know why they're listed.
</Tip>

## Sync teams from the system that already knows your org

Don't maintain team membership by hand in Cortex if another system already does it.

| If your org structure lives in | Use it for | Set up |
| - | - | - |
| An HR system (Workday, BambooHR) | Teams, members, and reporting lines | [Workday](/ingesting-data-into-cortex/integrations/workday), [BambooHR](/ingesting-data-into-cortex/integrations/bamboohr) |
| An identity provider (Okta, Entra ID, Google) | Team membership from groups | [Okta](/ingesting-data-into-cortex/integrations/okta), [Entra ID](/ingesting-data-into-cortex/integrations/entraid), [Google](/ingesting-data-into-cortex/integrations/google/connecting-entities-to-google-cloud-platform) |
| A Git provider (GitHub, GitLab, Bitbucket, Azure DevOps) | Team membership from Git teams, plus ownership recommendations | [GitHub](/ingesting-data-into-cortex/integrations/github), [GitLab](/ingesting-data-into-cortex/integrations/gitlab), [Bitbucket](/ingesting-data-into-cortex/integrations/bitbucket), [Azure DevOps](/ingesting-data-into-cortex/integrations/azuredevops) |
| ServiceNow | Teams and relationships from table mappings | [ServiceNow](/ingesting-data-into-cortex/integrations/servicenow) |

Pick one system as the source of team membership. Mixing sources for the same team makes it hard to tell why someone was added or removed.

If you sync team roles, turn on **Sync team roles from identity providers** in **Settings** > **Entities** > **Teams**. Members imported without a role can't verify entities when a verification period requires a role.

## Set up identity mappings first

Cortex matches people across tools with [identity mappings](/configure/settings/managing-users/identity-mapping). Configure them before you roll out ownership, because several features silently do nothing without them:

* The **Mine** tab and Engineering homepage can't show what you own.
* The **Editor** label doesn't appear for team ownership entity editing.
* Team metrics in Eng Intelligence come back empty.

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

## Choose one source of truth per entity type

Owners can come from the UI, YAML, the API, or an integration. Decide per entity type where owners are managed, and stick to it.

<AccordionGroup>
  <Accordion title="Cortex UI">
    Manage owners in **Configure entity** > **Owners**. This is the fastest way to accept ownership recommendations in bulk.

    Keep UI editing enabled for these entity types, and avoid also defining owners in YAML.
  </Accordion>

  <Accordion title="GitOps">
    Manage owners in `x-cortex-owners` alongside the code. Changes go through review, and history lives in Git.

    Disable UI editing for these entity types in **Settings > GitOps**. If UI editing is enabled, commits to those entities aren't reflected in Cortex. See [GitOps settings](/configure/settings/gitops-settings) for more information.

    With GitOps, you can view ownership recommendations but can't accept them from the UI. Copy the recommended team into YAML instead.
  </Accordion>
</AccordionGroup>

To remove an owner, use the same method you used to add it. See [Viewing and managing ownership](/ingesting-data-into-cortex/entities-overview/entities/ownership/viewing-and-managing-ownership#removing-ownership).

## Use inheritance on purpose

Inheritance keeps children owned when nobody remembers to set an owner, but it can also add owners nobody expects. Choose a mode for each domain owner:

| Use | When | Example |
| - | - | - |
| `FALLBACK` | You want a safety net for children with no owner | The domain's team catches any new, unowned service |
| `APPEND` | A group must be on every child, regardless of its owners | A platform or security team that needs every notification |
| `NONE` | The owner is responsible for the domain itself, not its contents | Domain leads who own the domain's roadmap |

* Prefer `FALLBACK` over `APPEND`. Appended owners receive every child's notifications, which adds up fast in a large domain.
* Inherited owners can't verify data. If a domain team should verify a child, make it a direct owner.
* To remove an inherited owner, change its mode on the parent. See [Removing inherited ownership](/ingesting-data-into-cortex/entities-overview/entities/ownership/viewing-and-managing-ownership#removing-inherited-ownership).

<Info>
  Domain inheritance and team hierarchy are distinct concepts. Parent teams never become owners of their child teams' entities. Use **Include child teams** to see everything below a team instead.
</Info>

## Fill gaps with recommendations, then verify

After you import entities, use the [Ownership tool](/ingesting-data-into-cortex/entities-overview/entities/ownership/assigning-owners-to-entities#assigning-ownership-via-cortex-recommendations) to assign owners quickly.

<Steps>
  <Step title="Review recommendations in bulk">
    Go to **Tools** > **Ownership**, select entities, adjust the recommended teams, and click **Accept recommendations**. Recommendations come from a model that uses signals across your catalog, such as code contributions, related services, domain structure, and connected tools.
  </Step>

  <Step title="Assign the rest manually">
    Some entities won't have enough signal for a recommendation. Use the **Unowned entities** filter in your catalogs to find what's left.

    The more your catalog contains (descriptions, domains, team membership, and integrations), the more entities get a recommendation and the more accurate they are. Filling these in before you run the Ownership tool pays off.
  </Step>

  <Step title="Ask owners to confirm">
    Create a [data verification period](/configure/settings/entity-settings/verification) for the entities you just assigned, so each team confirms it really owns them. See [Verify services after AI-based auto-mapping](/guides/ai-excellence/verify-auto-mappings).
  </Step>
</Steps>

## Keep owners and on-call separate

Ownership and on-call answer different questions. Owners are accountable for an entity over time; on-call is who responds right now.

* Define owners in `x-cortex-owners` and on-call schedules in `x-cortex-oncall`.
* Don't use an on-call schedule or a Slack channel as a stand-in for an owner. Channels in the **Owners** block are contacts, not owners.
* Opsgenie can provide both. Its integration page (**Integrations >  Configurations > Opsgenie**) shows each block.

## Enforce ownership with Scorecards

Make missing ownership visible so it gets fixed:

* Start from the **Ownership Verification** Scorecard template in [Create a Scorecard](/standardize/scorecards/create#option-1-use-a-template). Failing entities appear as tasks on owners' homepages.
* Or add a rule to an existing Scorecard:

```text theme={null}
ownership.allOwners().length > 0
```

To require a team owner specifically, use `ownership.teams().length > 0`.

* Track the unowned count over time in the [Executive report](/improve/reports/executive-report).

## Restrict editing to owners when you're ready

Once ownership is accurate, you can limit who edits each entity to its owning team with [Team ownership entity editing](/ingesting-data-into-cortex/entities-overview/entities/adding-entities/teams/team-entity-editing). Turn it on after the steps above, not before. Only team ownership grants edit access, so check these first:

* **Entities owned only by individuals** have no owning team. Only users with broad edit permissions, or `Configure Catalogs`, can edit them. Add a team owner.
* **Inherited team owners count.** Members of a team that owns an entity through a domain can edit it.
* **Unmapped members** don't get the **Editor** label. Configure identity mappings first.

## Plan for reorgs

* **Archive, don't delete, old teams.** You can't add an archived team as an owner, which prevents new assignments to a team that no longer exists.
* **Watch for new team IDs.** In Workday, changing a team's supervisory org ID or name creates a new team. Reassign entities from the old team.
* **Clean up individual owners.** Search with `owner:` for departed users' emails and replace them with teams.
* **Re-run verification.** After a reorg, start a verification period so new teams confirm what they inherited.


## Related topics

- [How ownership works](/ingesting-data-into-cortex/entities-overview/entities/ownership.md)
- [Scorecard examples](/standardize/scorecards/scorecard-examples.md)
- [Reduce MTTA](/guides/incident-mgmt/reduce-mtta.md)