Assigning owners to entities

Cortex supports three ways to assign owners to an entity: accepting an automated recommendation, defining owners in the entity descriptor YAML, or adding them directly in the UI. For most teams, a combination of all three is common; automated recommendations to tackle unowned entities at scale, YAML for entities managed through GitOps, and the UI for quick edits.

Types of owners

Owners can be defined as:

• A team (recommended)

  • If you link a group from an external platform (such as Okta), Cortex automatically updates team membership when someone leaves your organization and is removed from your identity provider.

• An individual user

• Fallback or append settings configured in an entity's hierarchy

Methods for assigning ownership

Owners can be assigned:

• By accepting Cortex's automated recommendations for owners, based on repository activity

• By pulling information from third-party integrations in the entity descriptor YAML

  • Ownership can also be inherited via fallback or append configuration

• Directly in the Cortex UI

• Automatically if Cortex detects that an entity is owned by a team that does not yet exist in Cortex

  • If an entity's YAML references a team, but that team doesn't have a corresponding entry within Cortex, Cortex automatically creates the team. A label next to the team name denotes that team was Automatically created by Cortex.

Assigning ownership via Cortex recommendations

Ownership tool preview

Not seeing the results you expect? This is an early version of the Ownership tool. Please submit feedback via this form. Note the following considerations:

• This feature is supported for entities associated with a repository in GitHub, GitLab, or Azure DevOps. Mapping is done on a per repository basis, so mapping teams owners to file paths within a monorepo is not supported.

• You must have teams configured in Cortex and team members must be identity-mapped in order for Cortex to provide recommendations. The more teams and people you have mapped, the better the recommendations!

• Cortex analyzes the last six (6) months of data, so if a repository has not had code changes within that time period, we will not have a recommendation.

• To accept or reject the recommended owner, the user must have the Edit Entities permission.

• If you are using GitOps, you can view recommendations, but you cannot accept them from the UI.

Cortex analyzes repositories to automatically recommend team owners for unowned entities.

When Cortex has an ownership recommendation for an entity, it surfaces in the following places: the Ownership tool (Tools > Ownership), the Owners section of the entity details page overview, the Owners sidebar on the entity details page, and the import flow when adding entities.

Reviewing ownership recommendations per entity

To review and accept ownership recommendations, three conditions must be met: UI editing must be enabled for the entity type, the user must have entity-level access via RBAC or fine-grained access control, and the user must have the Edit Services and Edit Catalog roles.

1. Navigate to the entity details page of the entity to which you want to assign ownership.

2. In the upper-right corner, click Configure entity.

3. From the left entity details sidebar, click Owners.

4. Review the suggested owners. To accept a recommendation, select the checkbox next to the recommended owner, then click Add owners.

Reviewing ownership recommendations in bulk

Users with edit access to all entities can review and accept ownership recommendations in bulk. Users with edit access to only some entities can accept recommendations individually from each entity's details page.

1. From the main sidebar, expand Tools, then select Ownership. A list of recommendations for ownership is displayed.

   
2. Select the checkboxes next to the entities for which you want to accept ownership recommendations. Use the Team recommendation drop-down menu to add or remove teams.

3. At the top of the list, click Accept recommendations.

Assigning ownership via an entity descriptor

Use the x-cortex-owners field to define owners directly in your entity's YAML. Each owner is either a group (a team from Cortex or a connected integration) or an individual identified by email.

Cortex recognizes groups from the following integrations: Azure Active Directory, Azure DevOps, BambooHR, GitHub, GitLab, Google, Okta, Opsgenie, ServiceNow, and Workday.

x-cortex-owners:
  - type: group
    name: platform-engineering        # x-cortex-tag of the Cortex team
    provider: CORTEX
  - type: group
    name: cortexapps/payments-team    # GitHub org/team slug
    provider: GITHUB
  - type: group
    name: payments-oncall             # Opsgenie team name
    provider: OPSGENIE
  - type: email
    email: [e-mail]      # individual fallback owner
    description: Primary escalation contact

The provider field tells Cortex which system the group comes from. Supported values are: ACTIVE_DIRECTORY, AZURE_DEVOPS, BAMBOO_HR, CORTEX (use for teams defined natively in Cortex, not synced from an external integration), GITHUB, GITLAB, GOOGLE, OKTA, OPSGENIE, SERVICE_NOW, and WORKDAY.

The name field is case-sensitive. What it refers to depends on the provider:

• For CORTEX - The x-cortex-tag of the team in Cortex

• For all other providers - The upstream identifier for the group in that integration (e.g. an Okta group name, a GitHub org/team-slug)

The description field is optional on any owner entry and is purely for human reference.

Assigning ownership via the Cortex UI

Users with the Edit Entities or Edit Catalog role can assign ownership via the Cortex UI.

1. From the main sidebar, expand Catalogs, then select All entities.

2. Select the entity whose ownership you want to edit.

3. In the upper-right corner, click Configure entity.

4. From the left entity details sidebar, click Owners.

5. Do one or both of the following:

   1. To assign a team ownership:

      1. Locate the Teams section, then click Add.

         
      2. In the Add Teams side panel, select the team from the drop-down menu.

      3. Optionally, enter a description for the team.

      4. Click Add.

   2. To assign an individual user ownership:

      1. Locate the Users section, then click Add.

         
      2. In the User side panel, do one of the following:

         1. Select a Cortex user from the drop-down menu. To find a user not shown in the list, use the Search field.

         2. To add a user who is not listed in Cortex, enter their email address into the Email address field. The drop-down populates with the user's email address.

      3. Optionally, enter a description for the user.

      4. Click Add.