# Adding teams In Cortex, teams are a default entity type that bridge your organizational structure with your software catalog. Unlike a simple label or tag, a team in Cortex is a rich entity with its own details page, Scorecard performance tracking, on-call information, Slack channels, and dependency graph, making it the central hub for understanding who owns what and how those owners are performing. Teams also reflect real-world org structure through parent-child hierarchies, so you can model everything from individual squads up to entire departments. Whether you bring teams in from an identity provider like Okta or Workday, define them in YAML via GitOps, or create them manually in the UI, Cortex keeps team membership and ownership in sync so when your org changes, your catalog stays accurate without extra effort. Teams are also the foundation of ownership in Cortex. Rather than assign an entity to individual team members, you can assign ownership to an entire team. This makes it easy to assign multiple team members to an entity, and it ensures that when a team’s composition changes, ownership is updated accordingly. See [Defining ownership](/ingesting-data-into-cortex/entities-overview/entities/ownership.md). ## Adding team entities to Cortex Users with the `Edit Catalog` and `Edit Domains` permissions can add team entities to Cortex. When configuring an entity, you can't add archived teams as owners or archived entities as dependencies, parents, or children. Teams can be added manually, imported, defined in YAML via GitOps, or created via the API. ### Importing teams from an integration If you already have a source of truth for teams and members, integrate your identity provider to import them. Cortex syncs team pages daily, eliminating duplicate updates when membership changes. {% hint style="warning" %} You can only import entities from integrations that have already been configured. {% endhint %} Teams can be imported from the following integrations: * [Azure DevOps](/ingesting-data-into-cortex/integrations/azuredevops.md) * [BambooHR](/ingesting-data-into-cortex/integrations/bamboohr.md) * [Entra ID](/ingesting-data-into-cortex/integrations/entraid.md) * [GitHub](/ingesting-data-into-cortex/integrations/github.md) * [GitLab](/ingesting-data-into-cortex/integrations/gitlab.md) * [Google](/ingesting-data-into-cortex/integrations/google.md) * [Okta](/ingesting-data-into-cortex/integrations/okta.md) * [OpsGenie](/ingesting-data-into-cortex/integrations/opsgenie.md) * [ServiceNow](/ingesting-data-into-cortex/integrations/servicenow.md) * [Configure table mappings](/ingesting-data-into-cortex/integrations/servicenow.md#step-2-configure-table-mappings) before importing * [Workday](/ingesting-data-into-cortex/integrations/workday.md) * Optionally, enable [automatic import of discovered teams](#auto-import-teams) **To import teams from an integration**: 1. From the main sidebar, expand **Catalogs**, then select **All entities**. 2. In the upper-right corner, click **Import entities**. 3. Select **Import discovered entities**.
The 'Import discovered entities' tile is displayed.
4. Select the integration to import from.\ The **Select entities to import** page is displayed. 5. A list of entities from the integration is displayed. Select the checkboxes next to the entities you want to import. If you have a large volume of entities, click the **Filter icon** in the upper-right corner of the results list to select and apply entity type filters.
6. In the bottom-right corner, click **Next step**.\ The **Edit details** page is displayed. 7. Configure the following options. The options shown are filtered at runtime based on the `entityType` (e.g. 'Members' is team-only, 'Dependencies' excludes domains/teams) and whether the required integrations are enabled (e.g. 'Communications' requires Slack, 'On-call' requires Opsgenie/PagerDuty, etc.). 1. From the **Type** drop-down menu, select **Team.** 2. In the **Details** section**:** 1. Under **Entity name**, enter a name for the entity (required). 2. The **Cortex tag** field is auto-populated based on the name of the entity (required). Its a unique identifier for the entity. This is also known as the `x-cortex-tag`. 3. Under **Description**, enter a description of the entity to help others understand its purpose. 4. From the **Groups** drop-down menu**,** select a group or groups [to segment the entity](/ingesting-data-into-cortex/entities-overview/entities/groups.md). 3. In the **Members** section, click **Add member**. In the side panel, do the following: 1. Select a user from the drop-down menu OR enter their information manually. If entering the information manually: 1. Under **Name**, enter the user's first and last name. 2. Under **Email**, enter the user's email address. 3. Under **Description**, enter any relevant information about the user, e.g. their timezone. 4. From the **Team role** drop-down menu, select the user's team role. 5. Optionally, toggle on **Notifications** to turn on notifications for the user. See [Notifications](/configure/settings/notifications.md) for more information. 6. Click **Add**. 4. In the **Links** section, click **Add** to add links to external documentation, such as runbooks, docs, logs, or custom categories. 5. In the **Slack channels** section, click **Add** to link a Slack channel to the entity. If enabled, you'll receive notifications about the entity in the selected Slack channel. 6. In the **Parents** section, select a parent team or teams from the drop-down menu. This is where you configure the hierarchy for your entity, which can be visualized in the [relationship graph](/ingesting-data-into-cortex/entities-overview/entities/relationship-graph.md). 7. In the **Children** section, select children entities. This is where you configure the hierarchy for your entity, which can be visualized in the [relationship graph](/ingesting-data-into-cortex/entities-overview/entities/relationship-graph.md). 8. In the **Jira** section, click **Add** to connect the entity to Jira. In the side panel, do the following: 1. From the **Jira Service Type** drop-down menu, select the service type: 1. **Component** - The sub-sections of a project used to group issues. 2. **Label** - Text-based tags used to categorize and track issues. 3. **Space** - The area where teams organize, track, and manage their operational work. 2. From the **Alias** drop-down menu, select the service type's alias. 3. Depending on the service type you selected, configure the appropriate field: 1. Select a Jira component from the drop-down menu. 2. Enter the name of the label. 3. Select a Jira space from the drop-down menu. 4. Click **Add**. 9. In the **Jira JQL Query** section, select an alias from the drop-down menu. Enter a custom JQL query for the entity. 8. If you selected more than one entity, click **Next entity** in the bottom-right corner of the page.
The 'Next entity' link in the bottom-right corner of the page.
9. Click **Confirm import**.\ The entity is imported into Cortex. ### Manually adding teams If you don't have an identity provider with updated team information, you can create teams manually in Cortex. Teams are essential for effective ownership, so it's recommended to set them up even without a single source of truth. 1. From the main sidebar, expand **Catalogs**, then select **All entities**. 2. In the upper-right corner, click **Import entities**. 3. Select **Create entities manually**. 4. Configure the following options. The options shown are filtered at runtime based on the `entityType` (e.g. 'Members' is team-only, 'Dependencies' excludes domains/teams) and whether the required integrations are enabled (e.g. 'Communications' requires Slack, 'On-call' requires Opsgenie/PagerDuty, etc.). 1. From the **Type** drop-down menu, select **Team.** 2. In the **Details** section**:** 1. Under **Entity name**, enter a name for the entity (required). 2. The **Cortex tag** field is auto-populated based on the name of the entity (required). Its a unique identifier for the entity. This is also known as the `x-cortex-tag`. 3. Under **Description**, enter a description of the entity to help others understand its purpose. 4. From the **Groups** drop-down menu**,** select a group or groups [to segment the entity](/ingesting-data-into-cortex/entities-overview/entities/groups.md). 3. In the **Members** section, click **Add member**. In the side panel, do the following: 1. Select a user from the drop-down menu OR enter their information manually. If entering the information manually: 1. Under **Name**, enter the user's first and last name. 2. Under **Email**, enter the user's email address. 3. Under **Description**, enter any relevant information about the user, e.g. their timezone. 4. From the **Team role** drop-down menu, select the user's team role. 5. Optionally, toggle on **Notifications** to turn on notifications for the user. See [Notifications](/configure/settings/notifications.md) for more information. 6. Click **Add**. 4. In the **Links** section, click **Add** to add links to external documentation, such as runbooks, docs, logs, or custom categories. 5. In the **Slack channels** section, click **Add** to link a Slack channel to the entity. If enabled, you'll receive notifications about the entity in the selected Slack channel. 6. In the **Parents** section, select a parent team or teams from the drop-down menu. This is where you configure the hierarchy for your entity, which can be visualized in the [relationship graph](/ingesting-data-into-cortex/entities-overview/entities/relationship-graph.md). 7. In the **Children** section, select children entities. This is where you configure the hierarchy for your entity, which can be visualized in the [relationship graph](/ingesting-data-into-cortex/entities-overview/entities/relationship-graph.md). 8. In the **Jira** section, click **Add** to connect the entity to Jira. In the side panel, do the following: 1. From the **Jira Service Type** drop-down menu, select the service type: 1. **Component** - The sub-sections of a project used to group issues. 2. **Label** - Text-based tags used to categorize and track issues. 3. **Space** - The area where teams organize, track, and manage their operational work. 2. From the **Alias** drop-down menu, select the service type's alias. 3. Depending on the service type you selected, configure the appropriate field: 1. Select a Jira component from the drop-down menu. 2. Enter the name of the label. 3. Select a Jira space from the drop-down menu. 4. Click **Add**. 9. In the **Jira JQL Query** section, select an alias from the drop-down menu. Enter a custom JQL query for the entity. 5. If you selected more than one entity, click **Next entity** in the bottom-right corner of the page. 6. Click **Confirm import**.\ The entity is imported into Cortex. ### Adding a team in YAML via GitOps Teams can be created manually in Cortex or defined directly in the entity descriptor, where they can also be assigned as owners. See [Defining ownership](/ingesting-data-into-cortex/entities-overview/entities/ownership.md) for more information. If your entity is a team, you must specify `x-cortex-type` as `team` : ```yaml openapi: 3.0.1 info: title: On-Call Illuminati description: They know things. Dark things. Usually around 3am on a Friday. x-cortex-tag: on-call-illuminati x-cortex-type: team ``` {% hint style="info" %} The `x-cortex-team` tag has two main sections: `groups` and `members`. {% endhint %} #### **Adding groups to the team entity descriptor** Use `groups` to connect a team entity to a matching team on another platform you've integrated with Cortex (such as Okta, GitHub, or Azure AD). Only one group can be linked per team entity. For example, you can specify: ```yaml openapi: 3.0.1 info: title: Firewall Whisperers description: They don't block traffic, they have stern conversations with it. x-cortex-type: team x-cortex-tag: firewall-whisperers x-cortex-team: groups: - name: okta-firewall-whisperers provider: OKTA ``` Specifying `okta-firewall-whisperers` under `groups` populates your team with every member of that Okta group. Once linked, any entity that lists `okta-firewall-whisperers` in `x-cortex-owners` automatically recognizes `firewall-whisperers` as an owning team, no extra configuration required. For example, a service owned by the team would look like: ```yaml openapi: 3.0.1 info: title: Perimeter Defense API description: Handles ingress rules, packet inspection, and the occasional stern talking-to. x-cortex-type: service x-cortex-tag: perimeter-defense-api x-cortex-owners: - type: group name: okta-firewall-whisperers provider: OKTA ``` #### **Adding team members to the team entity descriptor** Use `members` when you need to define team membership directly in Cortex, rather than syncing from an external platform. This is useful when a team doesn't map cleanly to a single group in one of your integrations, or when you need finer-grained control over who belongs and in what role. For example, you can specify: ```yaml openapi: 3.0.1 info: title: Velocity Merchants description: They move fast and only sometimes break things. Mostly on Fridays. x-cortex-type: team x-cortex-tag: velocity-merchants x-cortex-team: members: - name: Sprint Shepherd email: sprint.shepherd@cortexlabs.io notificationsEnabled: true roles: - tag: product-manager - name: Merge Maestro email: merge.maestro@cortexlabs.io notificationsEnabled: true roles: - tag: engineering-manager - tag: manager ``` Members support roles, and a single member can hold more than one. When a member's email matches an active Cortex account, that user will see the team appear under their Mine tab in any catalog that includes teams. The `role` field is optional per member. Roles themselves [must be defined](/ingesting-data-into-cortex/entities-overview/entities/adding-entities/teams/team-roles.md) in the entity's settings page, under the **Teams** tab. {% hint style="info" %} The `role` field in member is optional. In order to be considered valid, a team must have a non-empty group. {% endhint %} #### **Team children** Use `x-cortex-children` to define sub-teams, letting you model your org structure as a hierarchy in Cortex. The full hierarchy is visible in the Teams catalog. {% hint style="info" %} Cortex derives hierarchy from what's declared in each YAML file, not from where those files live in your repository. {% endhint %} For example, you can specify: ```yaml openapi: 3.0.1 info: title: Platform Overlords description: They don't write features. They write the things that let others write features. x-cortex-tag: platform-overlords x-cortex-type: team x-cortex-children: - tag: infra-gremlins - tag: dev-experience-dreamers ``` #### **Team parents** `x-cortex-children` defines relationships top-down, but if it's more natural to declare a team's place in the hierarchy from its own YAML, use `x-cortex-parents` instead. Both approaches produce the same result; use whichever fits how your team's YAML is maintained. For example, you can specify: ```yaml openapi: 3.0.1 info: title: Microservices Anonymous description: I'm a checkout-service, and I depend on 47 other services. x-cortex-tag: microservices-anonymous x-cortex-type: team x-cortex-parents: - tag: platform-overlords - tag: engineering-org ``` #### **Example cortex.yaml** The example below shows a fully defined team entity combining groups, members, children, Slack, and PagerDuty. Note that the file doesn't need to be named `cortex.yaml` or `cortex.yml` . See [GitOps example repository structure](/configure/gitops.md#how-gitops-works-in-cortex) for more information. ```yaml openapi: 3.0.1 info: title: Latency Avengers description: Milliseconds are their nemesis. They have the dashboards to prove it. x-cortex-tag: latency-avengers x-cortex-type: team x-cortex-team: groups: - name: okta-latency-avengers provider: OKTA members: - name: P99 Wrangler email: p99.wrangler@cortexlabs.io notificationsEnabled: true - name: Cache Evangelist email: cache.evangelist@cortexlabs.io notificationsEnabled: true x-cortex-children: # children can be of type team - tag: frontend-speed-demons - tag: cdn-whisperers x-cortex-slack: channels: - name: latency-avengers notificationsEnabled: true description: For when dashboards go red and everyone's pinging everyone. # optional x-cortex-oncall: pagerduty: id: P99XQRS type: SCHEDULE ``` ### Adding a team via the Cortex API You can create, update, and delete teams using the Cortex API. See [Teams](/api/readme/teams.md) for more information. ## Editing a team entity Users with the `Edit Catalog` and `Edit Teams` permissions can edit team entities. Team entities can be modified at any time. Follow the steps below to edit a team entity. 1. Navigate to the entity's page. 2. In the upper-right corner, click **Configure entity**.\ The entity details page opens. 3. In the upper-right corner, select either **UI editor** or **YAML editor**. 4. Make your changes. Note that the Cortex tag is uneditable. 5. Click **Save changes**.\ The team entity is updated. {% hint style="info" %} It's possible to change the entity type via the Cortex YAML. See [Changing an entity's type](/ingesting-data-into-cortex/entities-overview/entities.md#changing-an-entitys-type) for more information. {% endhint %} --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.cortex.io/ingesting-data-into-cortex/entities-overview/entities/adding-entities/teams.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.