The Cortex YAML linter validates your cortex.yaml files for both general YAML syntax and Cortex-specific schema requirements, helping prevent ingestion of invalid or incomplete data into the platform.
This page references the built-in tool in the Cortex UI under Tools > YAML Linter. Note that there is also a linter tool built in to the Cortex GitHub app, which runs checks on pull requests when you use GitHub in a GitOps workflow.
Using the YAML linter
Validate a YAML file in the Cortex UI
In Cortex, navigate to .
Paste your YAML into the text editor, then in the upper right, click Validate YAML.
At the bottom of the screen, you will see a status banner:
If the format is correct: You will see a message stating that the YAML is valid:
Validation scope
The linter checks for valid YAML structure and ensures required Cortex fields (like openapi version, x-cortex-tag, etc.) are present. If a required field is not present, this results in an error and the YAML does not pass the linter check.
The linter also validates the format of Cortex-specific blocks (e.g., x-cortex-groups, x-cortex-firehydrant) but does not verify the correctness of referenced data (such as whether a group or monitor ID actually exists). If there is an issue for a Cortex block, such as a block that doesn't contain a value, you will see a warning; however, the YAML will still pass the linter check.
If you submit a file with templating syntax (e.g., Jinja or cookiecutter variables like {{ variable }}), the linter will fail because these are not valid YAML until rendered. Only fully rendered YAML files will pass validation.
If the YAML is invalid or missing required fields, the linter will return errors indicating the line and nature of the problem.
GitOps settings for the linter tool
If you are using GitHub in a workflow, you can adjust settings related to the linter. See for more information.
Cortex Documentation
Code is no longer the bottleneck. Everything else is.
Cortex is the Engineering Operations Platform that enables organizations to continuously improve their operational maturity and reduce developer friction – so that the whole organization operates as one. By unlocking a culture of engineering excellence, our customers reduce incidents, improve MTTR, and make it easier for developers to focus on building.
Get started with Cortex
Get started in minutes with Cortex's .
Cortex video overview
See an overview of Cortex below:
Accelerate the path to Engineering Excellence
We believe the foundation for Engineering Excellence starts with clear ownership and accountability. With ownership in place, drive complete visibility through the catalogs, a culture of continuous improvement using and , and consistent developer experience through self-service .
Learn how organizations drive Engineering Excellence with Cortex:
VELOCITY
Track, standardize, and accelerate developer productivity, maintain high code quality, and keep systems reliable.
Monitor cycle time, PR throughput, code coverage, and velocity trends with Eng Intelligence and dashboards.
EFFICIENCY
Align everyone to the same standards and provide structured ways to meet them.
Use to measure and set standards for consistency, resource utilization, and migrations.
Use
SECURITY
Continuously check services for security best practice adherence and drive patches with clear ownership and accountability.
Monitor encryption, dependency health, and vulnerability status with customizable Security Compliance templates.
RELIABILITY
Validate that every service meets operational requirements, continuously improve day-to-day operations, and give teams the context and tools to respond quickly when incidents happen.
Automate readiness and operational maturity with customizable templates.
Archiving entities
Archiving an entity allows you to remove it from active use while preserving its history and context.
You can configure Cortex to automatically archive entities when they are no longer detected in your integrations or when their corresponding YAML files are deleted. We recommend enabling this feature to keep your data up-to-date without manual effort. Learn more in .
It's also possible to manually archive entities in the Cortex UI or via the Cortex API, as described below.
How to archive and unarchive entities
Grouping entities
Groups are a tagging system that can be used to group a set of together, enabling a variety of use cases including:
Tagging
Use groups to segment entities.
If the format is not correct:
For issues with the format of a Cortex-specific block, you will see a warning banner:
For errors that cause the YAML to fail the linter check (such as missing a title or x-cortex-tag), you will see a banner that includes the error message and which line is affected:
Set clear standards and enforce best practices across teams and services with Scorecards.
Automate common tasks like scaffolding new services or handling migrations with Workflows.
Get quick answers about your workspace via Cortex MCP, allowing for faster decision making.
How do different personas drive velocity with Cortex?
Engineering leaders: Leverage the productivity metrics from Eng Intelligence during performance reviews and coaching conversations.
Platform engineers: Set up a Workflow to request access to commonly used tools, making the process a single approval flow that integrates into their existing tooling.
to ensure that teams are aligned and migrations are completed.
How do different personas drive efficiency with Cortex?
Engineering leaders: Manage cloud costs and improve resource utilization with Scorecards.
Platform engineers: Use Scorecards to ensure standards are met during a migration, accelerating project timelines.
Developers: Use the Engineering homepage to gain insight into their tasks and priorities.
Remediate vulnerabilities and compliance by priority and deadline with clear Initiatives.
Ensure consistent rollouts and CI/CD processes using Workflows.
How do different personas drive security with Cortex?
Engineering leaders: Use reports to understand current security posture, allowing them to guide their teams with actionable insights.
SREs: Use Scorecards to maintain catalogs, enabling faster incident response.
Security engineers: Automate security checks and flag noncompliant services with Scorecards, ensure consistency and standardization of tasks with Workflows.
How do different personas drive reliability with Cortex?
Engineering leaders: Use reports to get a unified view of organization-wide service health, allowing them to prioritize reliability Initiatives across teams.
Developers: Use Scorecards to gain clear visibility into whether their services meet standards for reliability.
SREs: Automate production readiness checks via Scorecards, allowing them to move from reactive fire-fighting to proactive incident prevention.
Platform engineers: Automate best practice enforcement via Scorecards. Use Iniatives to , ensuring reliability improvements are systematically addressed.
Use Cortex to automate best practices and streamline actions for use cases like Production Readiness, AI Maturity, Incident Management, and more.
🤖Use Cortex MCP
Make decisions faster by querying your workspace's information in natural language
⚡Connect Data
Start tracking ownership. Learn how to manage your entities and integrate with essential tools, like Git, APM, and more.
🖥️Configure GitOps
Configure a GitOps workflow to manage entities in your Cortex workspace.
🔗Explore the API
Build automation with Cortex as your source of truth for Catalog, Scorecards, and more.
📈Continuously Improve
Measure baselines and identify bottlenecks. Take action and watch trends improve in real time.
To archive entities, your user or API key must have the Archive entities permission. To unarchive entities, your user or API key must have the Configure entities permission.
By default, archived entities do not appear in the lists on "All entities" or in catalogs, but you can choose to include archived entities in your view.
To include archived entities:
Click Display at the top of the list.
Toggle on the setting for Show archived.
Note that this setting is not persistent when you navigate away from the page.
An entity details page
On an entity's details page, if a related dependency, child entity, or parent entity has been archived, it will not be displayed under Relationships in the entity's sidebar.
If the entity itself has been archived, you will see an "Archived" flag appear next to its name:
Entity configuration
While configuring an entity, you cannot add an archived team as an owner. You cannot add archived entities as dependencies or as parent or child entities.
The discovered entities list
Cortex will tag detected changes to signify whether an entity or repository has been archived. Learn more in Viewing discovered entities.
For example, you may want a Scorecard to only apply to Python services or a catalog that only shows tier-0 services.
Reporting
You could aggregate Scorecard scores by a specific group, such as a tier.
For example, viewing a Production Readiness Scorecard broken down by tier.
While viewing an entity, its groups are listed in the upper right side of the page:
Click the group name to view a list of all other entities that are tagged with this group.
How to define and apply groups
You can create new groups in an entity's YAML, directly in the Cortex UI, or via the API. When creating a new group, it is applied to the entity where you are creating the group.
Note the following considerations:
If a group has been set in the entity descriptor YAML, an API call will not overwrite the existing value.
Groups created via the API will not appear in the entity descriptor YAML.
Groups created via the API cannot be removed via the Cortex UI.
To create a group in the UI:
Navigate to the entity that you want to apply a group to.
Click the magnifying glass icon at the bottom of the main nav, or click Catalogs > All entities and search for the entity from that page.
In the upper right corner of the entity page, click Configure entity.
Click into the Groups field.
To apply an existing group, type to search then click on the group.
To create a new group, type the group name into the field, then click the group name in the dropdown. The group will be created and applied to the entity.
At the bottom of the page, click Save.
Groups are defined as a list of tags.
Groups may not contain whitespace characters.
You can use the API to add groups to an entity. See the .
To determine whether or not to use groups or custom data, consider whether your use case would be considered "tagging" with a definite enum of values (backend vs frontend), or more freeform metadata availability-zones: [east, west].
What is the difference between x-cortex-service-groups and x-cortex-groups?
There is no difference between these. x-cortex-service-groups has been deprecated in favor of x-cortex-groups, but the change is backward-compatible.
Getting your data into Cortex is the foundation for data-driven decision making and improved accountability across your teams.
By connecting your services, repositories, teams, infrastructure, and more, Cortex can provide a complete, up-to-date view of your ecosystem. This powers the ability to track ownership of entities, enforce production readiness and other standards via Scorecards, standardize common developer Workflows for entities, and more. It also ensures your developers can find what they need, understand how everything fits together, and make better decisions at every stage of the development lifecycle.
How Cortex handles data modeling
Some internal developer portals start with too much rigidity or too little guidance. A rigid platform prevents you from correctly modeling relationships between key entities in your environment. An overly modular approach requires you to rebuild business logic for each use case, resulting in the same fractured experience you intended to solve for.
Cortex solves for this by giving you the flexibility to mirror your unique business logic across your data, and the structure to persist that logic everywhere:
Data models are foundational, but configurable.
Integrations are available, but extensible.
Experience is complete, but customizable.
With consistent developer workflow and a configurable experience, it's easier to accurately represent your services and infrastructure in Cortex. See an .
Need assistance with data modeling?
To ensure a smooth implementation, most of our customers partner with Cortex Professional Services (PS) for hands-on assistance, including expert guidance on data modeling. Contact [email protected] to learn more.
Connect your data
The pages in this section cover the following topics:
How to import and manage entities
An entity is an object that represents a software construct. Entities are represented in YAML and can pull in data from integrations. Entities can have dependencies, can be set up in a hierarchical structure, and can be connected to other entities through entity relationships. Entity standards can be ensured through Scorecards. Learn more in .
How to create and manage catalogs
Want to learn more? Check out the Cortex Academy course on , available to all Cortex customers and POVs.
Cortex data concepts reference table
Learn about the basic data concepts for Cortex below.
Concept
Definition
Viewing discovered entities
You may have over a hundred repositories in GitHub, and eventually, you will likely import all of them into Cortex. This much information can make it difficult to know at a glance that all repositories are accounted for and all new projects are being imported into and tracked within Cortex.
The discovered entities list (formerly known as the discovery audit) guarantees confidence in your catalogs by listing all changes that Cortex has detected. Cortex compares everything that exists within the system to what it discovers within your git tool, APM tool, Kubernetes cluster, and other crucial integrations, giving you insight into changes happening across your environments.
View the discovered entities
You can view discovered entities under Catalogs > All entities in the .
On this page, see a list of recent changes in your environment that aren't yet reflected in Cortex, including newly created repositories, services, and resources discovered from your integrations.
Filter the discovered entities list
The first time you view the discovered entities list, there may be a lot to review. To narrow the scope of your list and start with changes that are the highest priority for you, search or filter the list by integration or entity type.
To search, enter text into the search bar in the upper right corner of the list.
To filter, click Filter in the upper right corner of the list. Select your filtering criteria, then click Apply.
Importing and removing entities
Cortex will tag detected changes to signify whether an entity or repository has been discovered, archived, or deleted.
You can import, delete, or ignore the entities listed in Discovery audit.
Import discovered entities
If Cortex detects a new service or resource, you can import it directly from this page:
Click + in the row containing the new entity:
Configure the entity details.
For detailed instructions on creating a new entity, see the relevant docs page for the entity type: ,
Delete discovered entities
If Cortex no longer detects a given entity, you also have the ability to delete that entity or repository directly from this page:
Click the trash can icon in the row containing the entity:\
In the confirmation window, click Delete.
The confirmation window gives you the opportunity to review all potentially impacted services before deleting, so you don’t unintentionally remove something from Cortex.
Ignore discovered entities
If an event appears within the discovered entities list, but is irrelevant — for example, a test project that doesn’t need to be imported into Cortex — you can ignore it:
Click the hide icon in the row containing the entity:\
The entity will now appear in the Ignored tab. The ignore action is persistent, so the event won’t appear again within the discovered list.
From the ignored list, you can move the entity back to the Discovered tab by clicking the eye icon.
Troubleshooting and FAQ
Why do I not see all of my services from my APM provider in the discovered entities list?
Cortex supports a subset of integrations within the discovered entities list:
Datadog
ECS
Version control (Azure DevOps, Bitbucket, GitHub, GitLab)
Instana
Relationship graph
In Cortex, use the relationship graph to better understand:
Dependencies
Visualize how entities relate to one another
Manage entities using Cortex Terraform Provider
The acts as a bridge between Terraform and the Cortex platform, allowing you to manage and provision Cortex resources (such as , , and ) using Terraform’s infrastructure-as-code approach. The provider is a wrapper around the public Cortex API and is maintained by the Cortex team, with shared ownership and ongoing support for customers who use it.
Cortex integrates with Terraform in two different ways, depending on whether you want to manage Cortex resources using Terraform, or use Cortex to drive Terraform runs for your infrastructure.
To learn about using Cortex to drive Terraform runs, see .
Humanitec
offers products to build on top of your Engineering Operations Platform for containerized workloads.
Integrating Humanitec with Cortex allows you to run a Humanitec pipeline directly from Cortex.
How to integrate Humanitec with Cortex
Instana
Overview
is a tool used for monitoring and performance management. Integrate Instana with Cortex allows you to pull in services from Instana.
Managing the catalog as code
Many Cortex customers manage their entire service catalog and engineering standards as code using the Cortex Terraform Provider.
Expand the tiles below for examples on how to handle different use cases with this approach.
Service catalog as code
Goal: Any time a new microservice or app is created (via a Terraform module, template repo, or platform workflow), it’s automatically added to the Cortex catalog with the right metadata and ownership.
How to do it:
Use the cortex_catalog_entity resource to create and update services, libraries, or other catalog entities from Terraform.
Attach extra metadata with cortex_catalog_entity_custom_data – e.g. tier, business_unit, cost_center, “is_internally_facing”, etc.
Optionally define departments (e.g. “Payments”, “Growth”) with cortex_department, and link services/teams to those for reporting and ownership.
Scorecards and standards as code
Goal: Treat operational standards (SRE, security, compliance, production-readiness gates) as code that lives next to infrastructure, reviewed via PRs and rolled out safely.
How to do it:
Define scorecards via the cortex_scorecard resource. It supports:
an evaluation window (how often to evaluate, min every 4 hours)
a filter to target specific entity types or groups
Use cortex_resource_definition to standardize external signals that Scorecards rely on (e.g. “has SLO in Datadog”, “has PagerDuty service”, “has runbook link”).
Manage changes to standards through Git review: PRs update the Terraform code, then Terraform updates the Cortex Scorecards and resources.
API contracts and org model as code
Goal: Ensure that API documentation and org metadata are always in sync, accurate, and consistent across environments.
How to do it:
Use cortex_catalog_entity_openapi to attach OpenAPI specs (YAML/JSON) to catalog entities in Cortex, keyed by the entity’s tag/ID.
Keep department and ownership structure in Terraform via cortex_department and catalog entity custom data (e.g., department, team, criticality).
When infrastructure changes (e.g., new API version, team moves between org units), updating Terraform automatically pushes the new OpenAPI spec + org metadata into Cortex.
Cortex will pull recent changes from Instana into the discovered entities list. Here, you can find new entities in Instana that have not been imported into the catalog.
View integration logs
This feature is available to Cortex cloud customers.
The following options are available to get assistance from the Cortex Customer Engineering team:
Email: [email protected], or open a support ticket in the in app Resource Center
Slack: Users with a connected Slack channel will have a workflow added to their account. From here, you can either @CortexTechnicalSupport or add a :ticket: reaction to a question in Slack, and the team will respond directly.
Don’t have a Slack channel? Talk with your Customer Success Manager.
Catalogs are a defined selection of entities. You can use them to track and store information about all the components that make up your infrastructure. Learn more in Managing catalogs.
Integrations
Cortex supports pulling data across a broad set of integrations to create a single pane of glass. See all integrations in the sub-pages under Integrations.
Catalog
A folder-like visual container, for UI organization only
Group
A logical collection for search, filtering, and reporting. Similar to a label or tag set.
Dependency
One entity relies on another. Enables impact analysis and notifications.
Ownership
Accountability link between a team and entity.
Entity relationship
Generic link between entities
Hierarchy
Parent-child or part-of structure. Enables inheritance ownership.
Team
A group of humans responsible for something
Service
A running technical component (API, job, infra service)
Domain
A foundational grouping layer that represents a logical or functional area of your organization. The bone structure of your Cortex model. Domains form the base hierarchy that organizes entities (services, systems, pipelines) under stable, high-level boundaries. Each domain reflects a cohesive area of ownership, business function, or technical responsibility.
See a hierarchical diagram of your software architecture
Teams
View your company's team structure
View the relationship graph
You can access the relationship graph from the main nav: Navigate to Tools > Relationship graphs. By default, the page displays all entities with dependencies and how they relate to one another.
Filter the relationship graph
If you have more than 500 nodes in the graph, you must select a filter before the graph will display.
Select a relationship type
At the top of the page, choose which relationships you want to view: Dependencies, domains, or teams.
Select dependencies, domains, or teams.
Filter the graph
You can apply filters to narrow the scope of the graph:
Click Filters at the top of the page.
Apply filters for the following options:
Sources
Groups
Entity types
Degrees from selected node
The page will automatically apply your selected filters and reload the visualization.
Select a display option
At the top of the graph, click Display options to select:
A Scorecard to filter the graph by
Whether to hide team nodes without children
Whether to hide archived entities
View more details on an entity
In the graph, click an entity to open a modal with the ability to:
Filter by this node
Go directly to its entity details page
View a list of its child entities or dependencies
Click a node to open a modal with more information.
Adjust appearance settings
You must have the Configure settings permission.
Under Settings > Relationship graph, you can select whether to display dependencies, domains, or teams by default when you first open the relationship graph.
Prerequisites
Before getting started:
You should have an app with a working pipeline configured in Humanitec.
Create a service user in Humanitec, and create an API token in Humanitec for the service user.
Add an HTTP request block to your Workflow. Configure the block:
Block name: Enter a descriptive name for the block.
Slug: Enter a unique identifier for the block.
HTTP method: Select POST.
URL: Enter a Humanitec API URL based on the Humanitec call , e.g., https://api.humanitec.io/orgs/<your-Humanitec-org>/<your-app-ID>/pipelines/<pipeline-ID>/runs
At the bottom of the side panel, click Save.
Make any other necessary changes to your Workflow, then in the upper right corner of the page, click Save workflow.
In your Humanitec workspace under your app's pipelines, you will see the run listed under the Runs tab:
Example using Cortex with AWS, Humanitec, and Terraform
See the video below where a member of the Humanitec team walks through advanced end-to-end setup on AWS using Cortex, Humanitec as the orchestrator, and Terraform modules deployed via ECS runners. The video demonstrates detecting a policy violation and remediating it.
We’re excited for you to start using Cortex to achieve engineering excellence! If you don’t have an account yet, sign up for a demo.
This guide walks through setting up your account, configuring your first integrations, and connecting your entities — services, infrastructure, teams, and more — with Cortex. After you’ve followed these steps, reach out to the Cortex team with any questions you have.
Need additional guidance?
To ensure a smooth implementation, partner with Cortex Professional Services (PS) for expert guidance and hands-on assistance with data modeling, entity ownership, and more. Reach out to [email protected] to learn how we can support your implementation and adoption journey.
Looking for a quick introduction to Cortex? Check out the .
Getting started in Cortex
When you first log in to your Cortex workspace, you are prompted through the steps of configuring your account and connecting data. See the video below for a demonstration:
Following the streamlined onboarding
Step 1: Log in and configure your workspace
You can access your Cortex workspace using the workspace ID provided to you by your Cortex team. Or, if you are deploying Cortex on-premises, the Cortex team will provide you with access to an installer.
SSO setup
Your initial login will be configured to use Google for Single Sign-On (SSO).
If you do not use a Google domain email address, work with the Cortex team on initial access and .
Add users
Step 2: Configure integrations
Before importing entities, you may want to think through your data modeling approach. Learn more below under .
You will be prompted to connect your tools:
Integrate with version control and teams
Version control
Step 3: Configure identity mappings and review services
Configure identity mappings
After connecting version control and teams, you will be prompted to for users, allowing you to match user identities across different systems.
Review mapped services
Cortex will recommend connections for your services. For example, if you connected PagerDuty, Slack, and Jira, then Cortex will recommend an entity's on-call service, Slack channel, and Jira project. You can change these details before confirming the import.
Step 4: View catalog or create a Scorecard
Congratulations - you are on the path to achieving engineering excellence with Cortex!
After completing the onboarding flow, you will be prompted to create your first Scorecard or to .
For additional information and resources, see the section below: .
Create your first Scorecard
You can use to establish best practices, track migration, promote accountability among teams, enforce standardization across entities, or define maturity standards.
Additional information
Data modeling
Before importing entities, consider your data modeling approach.
Identify the key entities that you want to represent in your Cortex catalogs.
Read more about entities and the default entity types in the .
If needed, .
Tracking ownership with teams
serve as both an entity representing your organization in Cortex and as owners for entities in the catalogs. Ownership is a core use case of Cortex, as organizations seek to establish clear ownership of services, data, and other entities. Ownership also drives which users will receive notifications from Cortex, including alerts for on-call changes, when an entity is re-evaluated and its Scorecard changes, and more.
Teams can be assessed via , interact with integrations, and leverage custom data. They can also be configured in a hierarchy. In addition, team data can be tracked and analyzed in . You can manually create teams in Cortex or you can pull in teams from integrations.
Go further
Create to segment your entities.
Explore additional resources
Now that you’ve completed your first steps, we recommend exploring the following topics:
: You can manage your entities directly in the browser-based Cortex workspace, or you can follow a GitOps approach. We recommend starting in your Cortex workspace, then if desired, switching to GitOps before a broader rollout at your organization.
: Automate running sequential actions and development workflows based on contextual data that exist inside your workspace.
Reach out to your Customer Success Manager for more information on enabling this feature.
Go further
Ready to learn more? Check out the to explore courses across core product areas and build expertise on the Cortex platform!
Using On-call Assistant for incidents
Cortex’s On-call Assistant leverages the PagerDuty integration to automatically surface the most vital information about entity health and metadata when an incident is triggered. On-call Assistant notifies the user(s) responsible for an incident via Slack, including information about the affected entity, recent deployments, ownership, and links to get more details, including dependencies, runbooks, and logs.
On-call Assistant helps users respond to incidents in real time, simplifying the incident response process and helping to reduce MTTR. It can also drive adoption and engagement through links to the catalogs and Scorecards.
How On-call Assistant works
Notifications
When an incident is triggered in PagerDuty, On-call Assistant will notify relevant users via . This alert will include information about the affected entity, deploy details, and ownership information so an on-call team member can reach out to other relevant parties about the incident.
Developers can access entity information that is already in Cortex directly from the Slack notification to quickly resolve issues. On-call Assistant provides a direct link to view the alert in PagerDuty, so you can also quickly access the incident from its source.
View runbooks and other links
View dependencies
Enabling On-call Assistant
Prerequisites
You must have the configured.
You must create an in PagerDuty with the Write permission.
If you create an API key with Read-only permissions, you will also need to configure a webhook to get the On-call Assistant working.
Enable On-call Assistant in Cortex
To enable, navigate to and toggle on Enable On-call Assistant.
If you added PagerDuty API key with Write permissions, enabling the On-Call Assistant will create a webhook subscription in PagerDuty, allowing Cortex to receive events when incidents are triggered, escalated, or unacknowledged.
Configure a webhook for read-only API keys
If you added PagerDuty API key with Read-only permissions, you must also configure a webhook subscription.
In Cortex, on the , click Configure webhook.
Copy the webhook URL. You will need this in the next steps.
In PagerDuty, add a new webhook.
Coralogix
Overview
Coralogix is an observability and security platform. Integrate Cortex with Coralogix to drive insights into alerts.
After setting up the integration, relevant alerts from Coralogix will appear in your entity pages. While viewing an entity, click Integrations > Coralogix in its sidebar to view the list of alerts.
How to configure Coralogix with Cortex
Prerequisites
Before getting started, generate a .
Step 1: Configure the integration in Cortex
In Cortex, navigate to the
Click Integrations from the main nav. Search for and select Coralogix.
Click Add configuration.
How to connect Cortex entities to Coralogix
Discovery
By default, Cortex will use the entity name or (e.g. my-service) as the "best guess" for the Coralogix alert application name. For example, if your entity name is "My Service" and your Cortex tag is “my-service”, then the corresponding application name in Coralogix should be “My Service” or "my-service".
If your Coralogix application names don’t cleanly match the Cortex tag, you can override this in the Cortex entity descriptor.
Editing the entity descriptor
Coralogix alerts can be listed in the Catalog under the Coralogix section. We support application names in the YAML for pulling Coralogix alerts.
Using the Coralogix integration
Scorecards and CQL
With the Coralogix integration, you can create Scorecard rules and write CQL queries based on Coralogix alerts.
See more examples in the in Cortex.
Check if Coralogix application is set
Check if entity has a registered Coralogix application in its entity descriptor. If no registration exists, we'll try to automatically detect which corresponding Coralogix application is associated with the entity.
Definition:coralogix (==/!=) null: Boolean
Example
You could write a rule that checks whether an entity has a Coralogix application set:
Alerts
List of alerts, filterable on status
Definition:coralogix.alerts(): List
Example
You could write a rule that checks whether an entity has at least 3 alerts:
You could write a rule that checks whether an entity has no alerts and status triggered:
View integration logs
This feature is available to Cortex cloud customers.
On the integration settings page, click the Logs tab to view logs from the last 7 days. Learn more in .
Scorecard rule filters
Rule filters allow you to apply a Scorecard rule only to specific entities. It's helpful to use a rule filter when a rule doesn’t apply to every entity or every group.
You can apply a filter in the Cortex UI while building out your Scorecard rules, or you can write a custom CQL query to filter your rule.
How to set up a Scorecard rule filter
When , click and expand Restrict rule to specific groups.
Select the relevant groups to include or exclude.
Or, if you prefer to write a CQL query, click Switch to CQL under the group fields.
Click Save rule.
See the for instructions on the overall process of creating a Scorecard.
You can also edit an existing Scorecard to add a filter to a rule.
Example Scorecard rule filter
For example, let's say that entities in the "billing" group don't need to have SLOs set up properly.
In the rule "Has SLOs set up," apply a filter to exclude the "billing" group:
After saving the rule with the excluded group, view the Scorecard. Any entities in the "billing" group will not be scored against the "Has SLOs set up" rule. The rule will not appear as a passing or a failing rule; it will not be included at all.
View the filter on the Scorecard home page
Once a rule filter has been applied, you can still see it on a Scorecard’s home page. Navigate to the Rules tab and expand the rule to confirm it has been exempted.
Add services
Services are a default entity type in Cortex, used for entities such as microservices, libraries, components, etc – essentially any codebase-like module.
View services
To view services, click Catalogs > Services from the main nav.
When you open the Services page, you'll see tabs labeled Mine and All, which denote services you own and all services visible to you in your Cortex workspace.
BambooHR
Overview
is a Human Resources Information System (HRIS) solution that allows you to define organizational membership. Integrate Cortex with BambooHR to automatically sync team memberships, giving you insight into entity ownership.
CircleCI
is continuous integration and continuous delivery platform that can be used to implement DevOps best practices.
Integrating CircleCI with Cortex allows you to:
in Cortex
Create that track progress and drive alignment on projects involving your CircleCI data
Grafana
is an open-source observability platform that provides monitoring and visual analytics for application performance. Use Grafana to your data, from bar charts and histograms to pie charts and geomaps.
Integrating Grafana with Cortex allows you to:
in Cortex
Create that include rules related to Grafana dashboards
Lightstep
Overview
, formerly known as Lightstep, helps you detect changes in your logs, metrics, and traces. Integrate Lightstep with Cortex to drive insights into SLOs and latency and error rate metrics.
Syntasso Kratix Enterprise (SKE)
is an enterprise-grade platform orchestrator built on , an open-source framework for building internal developer platforms on Kubernetes. SKE enables platform teams to deliver self-service infrastructure and services through composable, API-driven abstractions called .
Integrating SKE with Cortex allows you to:
Dynamically create in Cortex that map to Kratix Promises, enabling developers to self-service Kubernetes resources
Register and update entities in Cortex that represent Kubernetes resource definitions managed by SKE
The following options are available to get assistance from the Cortex Customer Engineering team:
Email: [email protected], or open a support ticket in the in app Resource Center
Slack: Users with a connected Slack channel will have a workflow added to their account. From here, you can either @CortexTechnicalSupport or add a :ticket: reaction to a question in Slack, and the team will respond directly.
Don’t have a Slack channel? Talk with your Customer Success Manager.
info:
x-cortex-coralogix:
applications:
- applicationName: my-app # application name tied to alert
alias: my-alias # alias is optional and only relevant if you have opted into multi account support
: Assign default roles to users or create and assign custom roles with granular permissions.
: You can use the IP allowlist to control where your Cortex workspace can be accessed from.
:
,
,
,
Configuring a Git provider allows you to discover and track ownership of entities, view important information about your repositories in Cortex, and use git data in Eng Intelligence to understand key metrics.
After you connect version control, Cortex will scan for repositories. You can choose whether to import all, or only selected, repositories.
Connecting your teams and team members in Cortex allows you to efficiently track ownership of entities. Learn more below under Tracking ownership with teams.
Configure other integrations
You can then configure additional integrations, such as:
Connecting project tracking tools allows you to link entities with their roadmaps, tickets, and initiatives.
Communication: ,
Configuring a communication provider allows you to receive timely notifications and collaborate seamlessly with team members.
Code quality: ,
Importing code coverage, technical debt metrics, and quality scores allows you to track engineering standards and enforce code quality requirements via Scorecards.
As you integrate additional tools with Cortex, it can also become possible to streamline work during an incident, efficiently track issues, monitor your code for vulnerabilities, and more. See the documentation for a full list of available integrations.
Go further
It would also be beneficial to configure integrations for categories such as:
When you first start using Cortex, we recommend creating an onboarding Scorecard to ensure that your entities are configured with the basics.
To get started:
From the main nav, click Scorecards.
Click Create Scorecard.
Cortex offers templates to help you get started with common use cases. Click the Onboarding Scorecard.
Review the default integrations, levels, and rules that are included in the template. You’ll get a chance to edit these on the next page. Click Continue.
Configure your Scorecard, making any modifications necessary.
For in-depth instructions on creating Scorecards, see Creating and editing Scorecards.
When you are finished, click Save Scorecard.
Go further
Use Initiatives to prioritize specific rules in a Scorecard and set deadlines for team members to accomplish tasks.
Create catalogs to track and store information about the entities that make up your infrastructure.
Enhance your entities with
to provide additional context and improve searchability.
Plugins: If you have a unique use case for tools or work with third parties that Cortex does not have an integration with or needs to pull in data from internal systems, we offer the option to build a plugin.
Eng Intelligence: View key metrics and high-level data to gain insights into services, bottlenecks in the pull request lifecycle, incident response, and more.
Reach out to your Customer Success Manager for more information on enabling this feature.
Workspace settings: Learn about additional settings and features to further customize your experience: API keys, audit logs, notifications, and more.
Paste the Cortex webhook URL into the Webhook URL field.
Choose Account for scope type.
Select only the following in Event Subscription:
incident.escalated
incident.reopened
incident.triggered
incident.unacknowledged
A secret will be generated. Copy the secret. You will need it in the next step.
Navigate back to the browser window where your Cortex instance is open. In the Webhook configuration Secret field, enter the secret that you generated in PagerDuty.
You can import services directly from third-party integrations:
In Cortex, navigate to Catalogs > All entities, then click Import entities.
Choose Import discovered entities.
Select the integration to import from.
On the following page, after the integration sync is complete, a list of entities from the integration are displayed. Check the boxes next to any entities you want to import.
If you have a large volume of entites, click Filter in the upper right corner of the results list to select and apply entity type filters.
At the bottom of the page, click Next step.
Edit the details for the entity:
Type: Select Service.
Entity name: Enter a human readable name.
If you selected more than one entity: After the first entity is configured, click the name of the next entity on the right to navigate to the detail editor for that entity.
Click Confirm import.
To create a service:
In the main nav of Cortex, click Catalogs > Services.
At the top of the Services page, click +Import entities.
Choose Create entities manually.
Service entity descriptor
A barebones spec file has the OpenAPI version, along with an info section that contains some basic details.
Required fields
The only required fields under info are the title, x-cortex-tag, and x-cortex-type. The description is optional, but we highly recommend adding descriptions to all of your entities.
You can create, update, and delete services using the .
Edit services
It is possible to edit entities after creating them:
Navigate to the entity's page.
In the upper right corner, click Configure entity.
Make any desired changes.
Note: The only field you cannot edit is the identifier.
The following options are available to get assistance from the Cortex Customer Engineering team:
Email: [email protected], or open a support ticket in the in app Resource Center
Slack: Users with a connected Slack channel will have a workflow added to their account. From here, you can either @CortexTechnicalSupport or add a :ticket: reaction to a question in Slack, and the team will respond directly.
Don’t have a Slack channel? Talk with your Customer Success Manager.
If you’re using a self-hosted instance of CircleCI, you’ll need to verify that your Cortex instance is able to reach the CircleCI instance.
We route our requests through a static IP address. Reach out to support at [email protected] to receive details about our static IP. If you're unable to directly allowlist our static IP, you can route requests through a secondary proxy in your network that has this IP allowlisted and have that proxy route traffic to your CircleCI instance.
Click Integrations from the main nav. Search for and select CircleCI.
Click Add configuration.
Configure the integration form:
Account alias: Enter an alias for this integration, used to tie entity registrations to different configurations.
API token: Enter the value of the API token you created in CircleCI.
Host: Enter the URL for your CircleCI instance if self-hosted, e.g.,
Click Save.
Configure the integration for multiple CircleCI accounts
The CircleCI integration has multi-account support. You can add a configuration for each additional by repeating the process above.
Each configuration requires an alias, which Cortex uses to correlate the designated with registrations for various entities. Registrations can also use a default configuration without a listed alias. You can edit aliases and default configurations from the CircleCI page in your Cortex settings. Select the edit icon next to a given configuration and toggle Set as default on. If you only have one configuration, it will automatically be set as the default.
How to connect Cortex entities to CircleCI
Editing the entity descriptor
You can define CircleCI projects in an entity's YAML descriptor. Add its project slug under the x-cortex-circle-ci block:
Using the CircleCI integration
Viewing CircleCI information on entity pages
When an entity has a CircleCI project defined in its YAML file, you will see metric and pipeline details on an entity's details page. Click CI/CD > CircleCI in the entity's sidebar to see this information.
Scorecards and CQL
With the CircleCI integration, you can create Scorecard rules and write CQL queries based on CircleCI metrics and pipelines.
The following options are available to get assistance from the Cortex Customer Engineering team:
Email: [email protected], or open a support ticket in the in app Resource Center
Slack: Users with a connected Slack channel will have a workflow added to their account. From here, you can either @CortexTechnicalSupport or add a :ticket: reaction to a question in Slack, and the team will respond directly.
Don’t have a Slack channel? Talk with your Customer Success Manager.
Click Integrations from the main nav. Search for and select Lightstep.
Click Add configuration.
Configure the Lightstep integration form:
Org ID: Enter your Lightstep organization ID.
You can find this in your Lightstep project settings.
Project ID
Click Save.
Linking SLOs in Cortex
You can create and manage SLOs by listing relevant latency SLIs through Streams. Cortex will pull data from Lightstep, and track against your specified SLO. For example:
Field
Description
streamId
ID of your Lightstep stream, which can be found in Lightstep, through the URL. https://app.lightstep.com//stream/my-stream/
percentile
Percentile latency for your given streamId, out of 1
target
Latency targets in ms. Latency is currently the only target supported
slo
Using the Lightstep integration
Entity pages
When an SLO is defined in an entity's descriptor, you'll see detailed data about SLOs in the Overview tab.
On the left side of an entity, click Monitoring > Lightstep to view the SLO query, target(s), current value for each SLO, a graph of SLO performance over time, and the period of time the SLO is being calculated for. For example, if the time listed is "7 days ago," then the SLO is looking at the time range starting 7 days ago to now.
Scorecards and CQL
With the Lightstep integration, you can create Scorecard rules and write CQL queries based on Lightstep SLOs.
SLOs associated with the entity via ID or tags. You can use this data to check whether an entity has SLOs associated with it, and if those SLOs are passing.
Definition:slos: List<SLO>
Example
In a Scorecard, you can use this expression to make sure an entity is passing its SLOs:
Use this expression to make sure latency Service Level Indicator (SLI) value is above 99.99%:
View integration logs
This feature is available to Cortex cloud customers.
The following options are available to get assistance from the Cortex Customer Engineering team:
Email: [email protected], or open a support ticket in the in app Resource Center
Slack: Users with a connected Slack channel will have a workflow added to their account. From here, you can either @CortexTechnicalSupport or add a :ticket: reaction to a question in Slack, and the team will respond directly.
Don’t have a Slack channel? Talk with your Customer Success Manager.
You should have Promises configured in your SKE environment.
You will need a Cortex API key to connect SKE to your Cortex workspace.
Configure the integration
SKE connects to Cortex via the Cortex API. Configuration is managed on the SKE side — refer to the SKE documentation for detailed setup instructions.
Once configured, SKE will automatically create and manage Workflows in Cortex based on the Promises defined in your platform.
How the integration works
Kratix Promises
Promises are the core abstraction in Kratix and SKE. A Promise defines a platform capability — such as a database, CI/CD pipeline, or Kubernetes cluster — as a self-service API. Promises encapsulate validation, provisioning, policy enforcement, and Day 2 lifecycle management into a single, governed contract between platform and development teams.
When SKE is integrated with Cortex, these Promises are surfaced as Workflows, allowing developers to request resources through the Cortex UI.
Using the SKE integration
As platform adoption grows, a common challenge emerges: What do we actually have, who owns it, and is it compliant? The SKE integration with Cortex connects orchestration with organizational visibility, helping teams treat their platform as a product — one that is not only easy to consume but also measurable, governable, and continuously improved.
Once configured, SKE dynamically creates, adds, and updates Promises for Kubernetes resource definitions in Cortex, giving platform teams a unified portal experience for managing platform capabilities.
Demo
See the video below for a demonstration of the Kratix integration with Cortex.
The following options are available to get assistance from the Cortex Customer Engineering team:
Email: [email protected], or open a support ticket in the in app Resource Center
Slack: Users with a connected Slack channel will have a workflow added to their account. From here, you can either @CortexTechnicalSupport or add a :ticket: reaction to a question in Slack, and the team will respond directly.
Don't have a Slack channel? Talk with your Customer Success Manager.
The teams getting the most value from the MCP have developed prompt patterns that fit naturally into their workflows. We've collated the most effective prompt patterns we've seen across different roles and workflows to build the list of prompt examples below. Think of it as a starting point for building your own prompt library, one that fits the specific needs of your team and organization.
Prompts for engineers
The best prompts for engineers eliminate context switching at the moments when focus matters most.
Understanding unfamiliar services
Tell me about the [service-name] service, including who owns it, what it does, and where the documentation lives.
This query pulls everything from your at once. You get ownership, a description of what the service does, links to documentation, and the team's communication channels. Instead of hunting across wikis, Slack, and GitHub, you have the context you need to start working.
Show me the dependencies for [service-name]. Which services does it depend on, and which services depend on it?
Understanding the dependency graph is critical when planning changes with potential downstream impact. This prompt reveals what might break and which teams need to be in the conversation before you make a move.
Which Scorecard is [service-name] failing, and what do I need to fix?
This prompt transforms maintenance from reactive to proactive. Instead of waiting for your platform team to flag issues or discovering gaps during an incident, you see exactly which Scorecards are failing and what specific checks need attention. You can address production readiness, security, or documentation gaps on your own schedule, before they become blockers.
During code review
Check the Scorecards for [service-name]. Does this service meet our production readiness standards?
Starting here when you're unfamiliar with a service changes the conversation. If the service is already failing key Scorecards, you'll know which questions to ask and where the risks actually are.
Show me recent incidents for [service-name].
Past incidents tell you where a service has been fragile. When you see that history before approving changes, you can evaluate whether the PR addresses root causes or introduces new failure modes.
Tracking your work
What Initiatives are assigned to the Engineering team, and what's the status of each?
This condenses your weekly status check into a single query. Run it at the start of your week or during standup and you get a complete picture of your Initiative commitments and their current state. Instead of navigating to the Cortex web UI or mentally tracking what you're responsible for, you see everything assigned to you without leaving your IDE or chat interface.
Show me the details for Initiative [initiative-name]. What still needs to be done?
When you're ready to make progress on a specific Initiative, this surfaces the remaining tasks and their current state. You know exactly what's left and where to focus.
Prompts for engineering leaders
The best prompts for engineering leaders are about trends, patterns, and the health of systems; these prompts surface the signals that inform strategic decisions.
Understanding team health
Show me MTTR trends over the last quarter. How has it changed?
Incident response either gets faster or it doesn't. If MTTR is climbing, something in your system has degraded. This prompt gives you the trend line and a clear signal to investigate process or tooling gaps.\
Which teams have the most failing Scorecards right now?
This surfaces which teams are struggling with compliance or buried in technical debt. The answer reveals where support and resources should flow. Instead of waiting for teams to escalate problems or discovering issues through incident patterns, you have a clear view of which teams need help right now. That visibility lets you have proactive conversations about priorities, staffing, or process changes before compliance gaps become production incidents.
Tracking AI adoption impact
How has AI adoption impacted MTTR and deployment frequency over the last quarter?
This connects AI spending directly to concrete business outcomes. When you run this query, you're comparing metrics before and after AI tool adoption. If MTTR dropped and deployment frequency increased after rolling out Copilot or similar tools, you have hard data to justify continued investment and potentially expand the rollout.
If the metrics haven't moved despite adoption, you need to ask different questions: Are teams actually using the tools? Do they need more training? Are the tools solving the wrong problems? The comparison gives you evidence to either double down on your AI strategy or course-correct before spending more.
Which teams have adopted AI tools, and how does their velocity compare to teams that haven't?
Spotting bottlenecks
Where are the biggest bottlenecks slowing down the Checkout team?
When a team's velocity drops unexpectedly, this surfaces the patterns that sprint metrics miss: services with high incident rates, missing documentation, or blocked Initiatives. You get signal, not speculation.
Show me services with the highest incident rates in the last month.
High incident rates point to deeper reliability issues. This tells you where to invest in stability before those services become everyone's problem.
Prompts for platform teams
The best prompts for platform teams show you where adoption is working, where it's stalled, and which teams need support.
Tracking standards adoption
Show me how teams are performing on the Production Readiness Scorecard. Which services are failing?
This gives you a complete view of compliance across the organization without manually checking each team's services. You see which teams are struggling to meet standards and which services create the most risk. The answer tells you where to focus your enablement efforts and which conversations to prioritize. Instead of discovering compliance gaps reactively during incidents or audits, you have a real-time picture of organizational health.
Which services don't have runbooks, and who owns them?
Missing runbooks are incidents waiting to happen. When something breaks at 3 AM, responders need clear guidance to restore service quickly. This prompt shows you exactly which services lack that critical documentation and who's responsible for creating it.
Managing Initiatives
Which services are blocking completion of the [initiative-name] Initiative?
When an initiative stalls, this identifies exactly which services or teams are holding things up. Now you know where to focus your attention and who needs support.
Show me progress on the Kubernetes Migration Initiative. Which teams are on track, and which are falling behind?
This surfaces real-time status across every team involved in the initiative without sending Slack messages or requesting manual updates. You get an immediate picture of which teams are making progress, which are stuck, and which haven't started. That visibility lets you direct support and resources to the teams that need it most, rather than treating every team the same or discovering delays only when deadlines slip.
Gap analysis
Which critical services are missing SLOs?
SLOs are foundational to reliability. This scopes the gap and identifies which services should be prioritized based on business impact before an incident forces the conversation.
Show me services without proper monitoring. What's missing?
Monitoring gaps are blind spots waiting to bite you during incidents. This surfaces which services need instrumentation and what specific monitoring is absent, so you can build a targeted remediation plan.
Prompts for SREs
The best prompts for SRE teams focus on proactive incident prevention or responding quickly to a incident in progress.
During incidents
Who's on call for [service-name] right now, and when was it last deployed?
The first question in almost every incident. One prompt gets you the owner, the on-call contact, and recent deployment history. You can escalate or start investigating without hunting through five different systems.
Show me recent deploys and changes for [service-name].
Most incidents trace back to recent changes. This gives you a timeline pointing to likely culprits so you can focus your investigation on what actually changed.
Show me the incident readiness Scorecard for [service-name]. Are we prepared to respond?
Proactive reliability work
Show me services with the highest MTTR in the last month.
High MTTR means certain services are consistently difficult to debug or restore. This tells you where reliability improvements will have the biggest impact on your time and your team's sanity.
Which critical services have had the most incidents recently?
Frequent incidents signal deeper problems that incident response won't fix. This helps you spot patterns and prioritize services that need architectural investigation, not just patches.
Show me services that are missing runbooks or escalation procedures.
Prompts for security engineering teams
The best prompts for security engineers help them monitor, audit, and enforce security posture across services.
Compliance monitoring
Which services are failing our SOC-2 Scorecard?
This gives you a view of SOC-2 compliance across the organization without manually checking each team's services. The answer tells you where to focus your efforts and which conversations to prioritize. Instead of discovering compliance gaps reactively during incidents or audits, you have a real-time picture of organizational health.
Proactive security health
Which services have no on-call rotation configured in PagerDuty?
When incidents happen, it's important to have on-call information readily available to ensure a fast response time.
What is the progress on my Security Initiative and what are some quick wins?
This surfaces real-time status for an Initiative without requesting manual updates from team members. You get an immediate picture of which entities are making progress and which are not. That visibility lets you direct support and resources to the teams that need it most.
Prompts for Product Managers
The best prompts for product managers focus on visibility, delivery health, and compliance to engineering standards that affect product velocity and quality.
Delivery and health metrics
Which services in the [product area] domain are failing their DORA metrics?
If you organize your data in Cortex by product area, Product Managers can get quick insight into which services in that product area domain are failing DORA metrics.
Initiatives and adoption tracking
Give me all currently active initiatives and ideas for how I can improve them
This helps product managers track progress on key initiatives and ensure teams are moving toward business goals.
Give me links to the docs and runbooks for [repository]
This helps product managers who need to find the documentation for a feature's related repository.
BugSnag
BugSnag is an application stability monitoring platform that provides error tracking and analytics.
Create Scorecards that include rules related to BugSnag errors
How to configure BugSnag with Cortex
Prerequisites
Before getting started:
Create a in your under "My account."
You must have the Configure integrations permission in Cortex.
If you're using a self-hosted instance of BugSnag, you'll need to verify that your Cortex instance is able to reach the BugSnag instance.
We route our requests through a static IP address. Reach out to support at to receive details about our static IP. If you're unable to directly allowlist our static IP, you can route requests through a secondary proxy in your network that has this IP allowlisted and have that proxy route traffic to your BugSnag instance.
Configure the integration in Cortex
In Cortex, navigate to the .
Click Integrations from the main nav. Search for and select BugSnag.
Click Add configuration.
After saving your configuration, you are redirected to the BugSnag integration settings page in Cortex. In the upper right corner of the page, click Test configuration to ensure BugSnag was configured properly.
How to connect Cortex entities to BugSnag projects
Discovery
By default, Cortex will use the (e.g. my-entity) as the "best guess" for BugSnag projects. For example, if your Cortex tag is my-entity, then the corresponding project in BugSnag should also be my-entity.
If your BugSnag projects don’t cleanly match the , you can override this in the Cortex entity descriptor.
Editing the entity descriptor
You can define projects under the x-cortex-bugsnag block:
Field
Description
Required
Using the BugSnag integration
Viewing BugSnag errors on an entity
Error data will appear on an . You can find the total number of detected errors and a full list on the Error tracking page in the entity's side panel. Error data is fetched live.
Each error in the list will display with an Error, Info, or Warning tag based on the applied to a given error in BugSnag.
Scorecards and CQL
With the BugSnag integration, you can create Scorecard rules and write CQL queries based on BugSnag projects and issues.
See more examples in the in Cortex.
Check if BugSnag is set
Check if an entity has a registered BugSnag project.
Definition:bugsnag (==/!=) null
Example
This expression can be used to write a Scorecard rule to make sure each entity has a registered BugSnag project:
This is also a good way to double-check that the integration is synced and reporting frequently.
Number of issues
Count all unresolved issues in BugSnag or counts number of issues for a given query. By default, will count all unresolved issues.
Definition:bugsnag.numOfIssues(query: Text | Null)
Example
For a Scorecard focused on operational maturity, you can pull in error data from BugSnag to make sure your entities have no or few errors.
View integration logs
This feature is available to Cortex cloud customers.
On the integration settings page, click the Logs tab to view logs from the last 7 days. Learn more in .
Still need help?
The following options are available to get assistance from the Cortex Customer Engineering team:
Email: , or open a support ticket in the in app Resource Center
Slack: Users with a connected Slack channel will have a workflow added to their account. From here, you can either @CortexTechnicalSupport or add a :ticket: reaction to a question in Slack, and the team will respond directly.
Don’t have a Slack channel? Talk with your Customer Success Manager.
Checkmarx
Overview
Checkmarx is an automated application security platform that checks source code for security vulnerabilities and compliance issues. Integrate Cortex with Checkmarx to drive insight into the vulnerabilities detected on your entities.
Before getting started, create a user with access to the sast_rest_api scope.
If you're using a self-hosted instance of Checkmarx, you'll need to verify that your Cortex instance is able to reach the Checkmarx instance.
We route our requests through a static IP address. Reach out to support at to receive details about our static IP. If you're unable to directly allowlist our static IP, you can route requests through a secondary proxy in your network that has this IP allowlisted and have that proxy route traffic to your Checkmarx instance.
Configure the integration in Cortex
In Cortex, navigate to the .
Click Integrations from the main nav. Search for and select Checkmarx.
Click Add configuration.
How to connect Cortex entities to Checkmarx
Discovery
By default, Cortex will use your associated Git repository (e.g. repo-name) or the service tag as the "best guess" for the Checkmarx project name.
If your repository and entity names don’t cleanly match the Checkmarx CxSAST project names, or if you have multiple Checkmarx projects for a service, you can add a Checkmarx project ID (recommended) or a Checkmarx project name in the Cortex entity descriptor.
Editing the entity descriptor
We recommend using the project ID as it is a unique identifier across projects.
Example using project IDs:
Example using both project IDs and names:
Using the Checkmarx integration
Entity pages
Once the integration is established, vulnerabilities pulled from Checkmarx will be available for each entity in the Code and Security block in the Overview tab.
While viewing an entity, click Code & security > Checkmarx. On this page, view the number of vulnerabilities per severity and a link directly to your Checkmarx instance.
Scorecards and CQL
With the Checkmarx integration, you can create Scorecard rules and write CQL queries based on Checkmarx details.
See more examples in the in Cortex.
Check if Checkmarx project is set
Check if entity has a registered Checkmarx project in its entity descriptor. If there is a Checkmarx project name, we will try and make sure that the project exists in Checkmarx.
Definition:checkmarx (==/!=) null: Boolean
Example
In a Scorecard, you can write a rule to check whether an entity has a Checkmarx project set:
Checkmarx scan risk
Get the maximum scan risk among the entity's project's latest scans
Definition:checkmarx.sastScanRisk(): Number
Example
In a Scorecard, you can write a rule to verify that an entity has no Checkmarx projects where the latest scan risk is higher than 35:
Number of Checkmarx vulnerabilities
Get the count of all vulnerabilities for an entity's Checkmarx project's last scan
Definition:checkmarx.numOfVulnerabilities(): Number
Example
In a Scorecard, you can write a rule to verify that an entity has no vulnerabilities with a severity of HIGH:
View integration logs
This feature is available to Cortex cloud customers.
On the integration settings page, click the Logs tab to view logs from the last 7 days. Learn more in .
FAQs and troubleshooting
Does Cortex support integrating with Checkmarx One?
No, Cortex does not currently support Checkmarx one. Only Checkmarx SAST is supported for this integration.
Still need help?
The following options are available to get assistance from the Cortex Customer Engineering team:
Email: , or open a support ticket in the in app Resource Center
Slack: Users with a connected Slack channel will have a workflow added to their account. From here, you can either @CortexTechnicalSupport or add a :ticket: reaction to a question in Slack, and the team will respond directly.
Don’t have a Slack channel? Talk with your Customer Success Manager.
Codecov
Codecov is a code coverage reporting platform that that monitors how much of your code has been tested and validated. Codecov analytics can be used to drive visibility into your microservice architecture and understand coverage trends over time.
Integrating Cortex with Codecov allows you to:
View code coverage details for entities directly in Cortex
Create Scorecards that track progress and drive alignment on projects involving your Codecov code coverage metrics
How to configure Codecov with Cortex
Prerequisites
Before getting started:
Create a .
Configure the integration in Cortex
In Cortex, navigate to the .
Click Integrations from the main nav. Search for and select Codecov.
Click Add configuration.
How to connect Cortex entities to Codecov
Auto discovery of Codecov projects
Cortex will use the GitHub, GitLab, Bitbucket, or Azure DevOps repository as the "best guess" for the corresponding Codecov project, since Codecov projects are connected to repositories. For example, if the GitHub repo associated with your Codecov instance is my-org/repo, then the entities in Cortex should also be associated with my-org/repo.
You can find the repository for a given entity in its YAML, defined in a block like the one below:
If the Codecov project you want to associate isn't the same as the repository, you can override this in the Cortex entity descriptor.
While Cortex uses the for discovery with many integrations, the repository is used for Codecov projects.
Editing the entity descriptor
Field
Description
Required
The value for repo should be the full repository because Codecov maps projects by repo.
Flags
Codecov's are used to categorize coverage reports for various features and tests in a given project. Flags allow you to set different statistics for different areas of your code base. For example, if you have a monorepo with multiple unique projects, you can use Codecov flags to evaluate each project with different test coverage metrics.
To pull flags into Cortex, define the flag line in the .
If you choose to configure with flags, discovery will be disabled; you would need to define the owner, repo, and provider lines.
Using the Codecov integration
Entity pages
With the Codecov integration, you can find code coverage details on an entity's details page as long as that entity is associated with a repo linked to your Codecov instance.
Click Code & security in the entity's sidebar to see the code coverage for that entity.
Scorecards and CQL
With the Codecov integration, you can create Scorecard rules and write CQL queries based on Codecov code coverage metrics.
See more examples in the in Cortex.
Code coverage
Code coverage for an entity's Git repository (out of 100)
Definition:codecov.codeCoverage()
Example
For a Scorecard focused on development maturity, you can set a rule to make sure code coverage for a given entity is at least 95%:
Set a threshold that is both challenging and realistic so there's an incentive for developers to improve.
Setting up a rule based on code coverage can serve as a secondary check to confirm an entity is synced with Codecov and reporting frequently.
View integration logs
This feature is available to Cortex cloud customers.
On the integration settings page, click the Logs tab to view logs from the last 7 days. Learn more in .
Still need help?
The following options are available to get assistance from the Cortex Customer Engineering team:
Email: , or open a support ticket in the in app Resource Center
Slack: Users with a connected Slack channel will have a workflow added to their account. From here, you can either @CortexTechnicalSupport or add a :ticket: reaction to a question in Slack, and the team will respond directly.
Don’t have a Slack channel? Talk with your Customer Success Manager.
Entra ID (Azure AD)
Microsoft Entra ID, formerly known as Azure Active Directory, is an identity service that provides SSO and authentication.
Integrating Cortex with Entra ID allows you to:
Automatically discover and track Entra ID teams and team memberships
Track ownership of entities
Create that track progress and drive alignment on projects involving your Entra ID teams
For information on configuring Entra ID SSO for logging in to Cortex, see the .
How to configure Entra ID with Cortex
Step 1: Register and configure a new Active Directory application
Follow Microsoft's documentation to .
In your Entra ID admin center, navigate to your new application, and then to API Permissions. Add the following permissions:
Microsoft APIs > Microsoft Graph > Application permissions > User > User.Read.All
Step 2: Configure the integration in Cortex
In Cortex, navigate to the .
Click Integrations from the main nav. Search for and select Entra ID.
Click Add configuration.
How to connect Cortex entities to Entra ID
Import entities from Entra ID
See the for instructions on importing entities.
Editing the entity descriptor
The group name is case-sensitive and should be exactly the same as in Entra ID.
Using the Entra ID integration
Teams page
Under Catalogs > Teams, you will see teams and team members pulled in from Entra ID.
Entity pages
If you have ownership of entities set up, then Azure AD teams and users will be listed in the Owners page for an entity.
Scorecards and CQL
With the Entra ID integration, you can create Scorecard rules and write CQL queries based on Entra ID teams.
See more examples in the in Cortex.
All ownership details
A special built-in type that supports a null check or a count check, used to enforce ownership of entities.
Definition:ownership: Ownership | Null
Example
An initial level in a security Scorecard might include a rule to ensure an entity has at least one team as an owner:
All owner details
List of owners, including team members and individual users, for each entity
Definition:ownership.allOwners()
Example
The Scorecard might include a rule to ensure that entity owners all have an email set:
View integration logs
This feature is available to Cortex cloud customers.
On the integration settings page, click the Logs tab to view logs from the last 7 days. Learn more in .
Background sync
Cortex conducts an ownership sync every day at 6 a.m. UTC.
FAQ and Troubleshooting
Why were all my Entra ID users unexpectedly deleted after rotating my client secret?
Updating your configuration can cause a temporary deletion of users. When you delete the old secret from your Azure AD configuration in Cortex, a sync is triggered to delete the users. The addition of the new secret to your configuration will trigger a sync to add the users. There may be a delay before seeing the users re-added.
Still need help?
The following options are available to get assistance from the Cortex Customer Engineering team:
Email: , or open a support ticket in the in app Resource Center
Slack: Users with a connected Slack channel will have a workflow added to their account. From here, you can either @CortexTechnicalSupport or add a :ticket: reaction to a question in Slack, and the team will respond directly.
Don’t have a Slack channel? Talk with your Customer Success Manager.
Okta
Overview
Okta is an identity and access management (IAM) platform. Integrate Cortex with Okta to drive insights into authentication and ownership.
After configuring the integration, you can set Okta teams and team members as owners of entities.
An Okta administrator, with at least the permissions, must .
Grant the following scopes for the API token:
okta.groups.read
Configure the integration in Cortex
In Cortex, navigate to the :
Click Integrations from the main nav. Search for and select Okta.
Click Add configuration.
How to connect Cortex entities to Okta
Import teams from Okta
See the for instructions on importing entities.
Team data syncs from Okta daily at 3 p.m. UTC.
Editing the entity descriptor
The group name is case-sensitive and should be exactly the same as in Okta.
Using the Okta integration
Scorecards and CQL
With the Okta integration, you can create Scorecard rules and write CQL queries based on Okta teams.
See more examples in the in Cortex.
All ownership details
A special built-in type that supports a null check or a count check, used to enforce ownership of entities.
Definition:ownership: Ownership | Null
Example
An initial level in a security Scorecard might include a rule to ensure an entity has at least one team as an owner:
All owner details
List of owners, including team members and individual users, for each entity
Definition:ownership.allOwners()
Example
The Scorecard might include a rule to ensure that entity owners all have an email set:
Team details
List of teams for each entity
Definition:ownership.teams(): List<Team>
Example
The Scorecard might include a rule to ensure that an entity owners all have a description and are not archived:
View integration logs
This feature is available to Cortex cloud customers.
On the integration settings page, click the Logs tab to view logs from the last 7 days. Learn more in .
Background sync
Cortex conducts an ownership sync for Okta teams every day at 3 p.m. UTC.
Troubleshooting and FAQ
I've added an API token but the login is still using Google.
To set up Okta for SSO, use the .
Still need help?
The following options are available to get assistance from the Cortex Customer Engineering team:
Email: , or open a support ticket in the in app Resource Center
Slack: Users with a connected Slack channel will have a workflow added to their account. From here, you can either @CortexTechnicalSupport or add a :ticket: reaction to a question in Slack, and the team will respond directly.
Don’t have a Slack channel? Talk with your Customer Success Manager.
Jenkins
Jenkins is an open source automation server which enables developers to build, test, and deploy software.
Integrating Jenkins with Cortex allows you to:
Send information about Jenkins deploys into Cortex
Note: This is only necessary if you plan to use Jenkins blocks in Cortex Workflows.
Step 1: Install the Cortex Deployer app
This integration uses the Cortex Deployer app, an open-source app that makes it easier for teams to push information about deploys to Cortex. This app leverages Cortex's .
Install the .
Step 2: Add a step to your Jenkins pipeline
Jenkins secrets
To use the Cortex Deployer app, you will need the x-cortex-tag and a Cortex API token. In the example below, both are defined as .
Jenkinsfile
To push information to Cortex about a deploy event, add a step to your Jenkins pipeline. Below is a snippet of what a Jenkinsfile may look like.
For more details about the options passed to the Docker image, please refer to the .
Step 3: Configure Jenkins in Cortex to enable Jenkins Workflow blocks
If you plan to use Jenkins blocks in Cortex Workflows, you will need to configure Jenkins in your Cortex workspace:
In Cortex, navigate to the :
Click Integrations from the main nav. Search for and select Jenkins.
Click +Add configuration.
Using the Jenkins integration
View Jenkins deploys on entity pages in Cortex
After you configure the integration, you will see data about Jenkins deploys in an :
On the entity overview, Jenkins deploys will appear under the Latest events section.
In the entity's sidebar, click Events to see a full list of events for the entity, including deploy events from Jenkins.
In the entity's sidebar, click CI/CD > Deploys to see data from the , including Jenkins deploys.
Kick off a Jenkins pipeline in a Cortex Workflow
You can use a Workflow to kick off a Jenkins pipeline. .
See Jenkins data in Eng Intelligence
Since the Jenkins integration uses Cortex's , Jenkins data is included in Eng Intelligence deploy metrics. Learn more about .
View integration logs
This feature is available to Cortex cloud customers.
On the integration settings page, click the Logs tab to view logs from the last 7 days. Learn more in .
Still need help?
The following options are available to get assistance from the Cortex Customer Engineering team:
Email: , or open a support ticket in the in app Resource Center
Slack: Users with a connected Slack channel will have a workflow added to their account. From here, you can either @CortexTechnicalSupport or add a :ticket: reaction to a question in Slack, and the team will respond directly.
Don’t have a Slack channel? Talk with your Customer Success Manager.
Sumo Logic
Overview
Sumo Logic is a cloud-based observability platform that provides log management and analytics. Integrate Sumo Logic with Cortex to drive insights into service-level objectives (SLOs).
How to configure Sumo Logic with Cortex
Prerequisites
Before getting started:
in Sumo Logic.
Determine your in Sumo Logic.
Configure the integration in Cortex
In Cortex, navigate to the :
Click Integrations from the main nav. Search for and select Sumo Logic.
Click Add configuration.
Linking SLOs in Cortex
You can create and manage SLOs by listing SLO IDs in the entity descriptor:
Using the Sumo Logic integration
Entity pages
When an SLO is defined in an entity's descriptor, you'll see an overview of SLO information in the Monitoring block on an overview.
On the left side of an entity, click Monitoring > Sumo Logic to view the SLO query, target(s), current value for each SLO, a graph of SLO performance over time, and the period of time the SLO is being calculated for. For example, if the time listed is "7 days ago," then the SLO is looking at the time range starting 7 days ago to now.
Scorecards and CQL
With the Sumo Logic integration, you can create Scorecard rules and write CQL queries based on Sumo Logic SLOs.
See more examples in the in Cortex.
SLOs
SLOs associated with the entity via ID or tags. You can use this data to check whether an entity has SLOs associated with it, and if those SLOs are passing.
Definition:slos: List<SLO>
Example
In a Scorecard, you can use this expression to make sure an entity is passing its SLOs:
Use this expression to make sure latency Service Level Indicator (SLI) value is above 99.99%:
View integration logs
This feature is available to Cortex cloud customers.
On the integration settings page, click the Logs tab to view logs from the last 7 days. Learn more in .
Still need help?
The following options are available to get assistance from the Cortex Customer Engineering team:
Email: , or open a support ticket in the in app Resource Center
Slack: Users with a connected Slack channel will have a workflow added to their account. From here, you can either @CortexTechnicalSupport or add a :ticket: reaction to a question in Slack, and the team will respond directly.
Don’t have a Slack channel? Talk with your Customer Success Manager.
Using JQ in Cortex
JQ is a lightweight, flexible command-line JSON processor that allows users to do arbitrary JSON manipulations.
Cortex leverages JQ within CQL to enable complex queries, including queries on YAML files. For instance:
The above query would cycle through the foo object and retrieve the length of all .property components. This type of query is often used on Kubernetes resources.
JQ and datatypes
JQ can provide additional flexibility around data types. For instance, let's say you have a string associated with a numerical value in your Custom Data.
If you wanted to query on the line value as a number rather than string, the following JQ functionality could be used within CQL:
This would result in the respective entity passing this CQL check.
JQ examples
The following examples demonstrate ways you could use JQ in Cortex:
Use JQ to implement conditional logic for selecting file paths dynamically
This checks if custom git data exists, uses the custom dockerfile path if present, or falls back to the default "Dockerfile" path.
Accessing properties with special characters
Use bracket notation to access JSON properties containing dots, slashes, or other special characters:
Handling null values
Prevent errors by checking for null values before accessing properties:
For Scorecard rules, you can use a similar approach:
Wildcard pattern matching
Find packages containing specific strings using the matches() function:
Finding team members by role
Filter team members by role using JQ:
Handling complex YAML structures
When working with complex YAML files like GitLab CI configurations:
Extract the scheme of an AWS load balancer for resource metadata
Or, for nested metadata:
Extracting version from pom.xml file
This query extracts the version number from a Maven pom.xml file. You might use this to automate dependency version checks:
Display a parent entity name in a CQL report
This query would allow you to display a parent entity name value, rather than an array, in a CQL report:
Apiiro
is an application security posture management (ASPM) platform that helps you understand and manage application security risks.
Integrating Apiiro with Cortex allows you to:
in Cortex, quickly connecting issues to entities and their owners
Use to drive quality improvements to your security practices relating to Apiiro applications, and set to prioritize tasks and set deadlines.
Rollbar
is an error tracking tool that helps developers discover and resolve crashes and errors.
Integrating Rollbar with Cortex allows you to:
, giving you insight into your entity's operational maturity
Create that include rules relating to error data from Rollbar, motivating team members to improve their code quality
LaunchDarkly
is a feature flag management platform.
Integrating Cortex with LaunchDarkly allows you to:
Track LaunchDarkly feature flags on entities in the catalog.
Create that track progress and drive alignment on projects involving your LaunchDarkly feature flags.
Veracode
is an automated security platform that identifies and remediates vulnerabilities in software applications. DAST, SAST, and SCA are supported.
Integrating Veracode with Cortex allows you to:
in Cortex
Create that track progress and drive alignment on Veracode vulnerability metrics
Scorecard rule exemptions
In some instances, a Scorecard rule might not apply to an entity. For example, a rule may be linked to an your team is actively working on and the failure notification may be irrelevant or noisy to developers. Or, in rarer cases, the Scorecard rule may not make sense for a given component, depending on the nature of that entity. In either case, rule exemptions allow you to filter out components that shouldn’t be evaluated by a specific rule.
With rule exemptions, entities are not marked as passing or failing — the rule simply does not apply to those entities. If you use point-based rules instead of levels, the exempted rule will not be included in the average for a component’s percentage score. If you use levels, an exempt rule allows an entity to progress to the next level.
Any user can , and Admins or users with the Configure Scorecard exemptions permission can . Users with the View Scorecard exemptions permission can view exemptions in Scorecards that have been requested by any user; without that permission, a user can only see their own requested exemptions.
Scorecards
Use Scorecards to establish best practices, track migration, promote accountability among teams, enforce standardization across entities, or define maturity standards.
1
Define
First, you create a Scorecard to set rules and define standards.
Learn more: .
2
Running and saving CQL queries
Learn about CQL basics and CQL tools (Query builder and CQL explorer) in .
Running a CQL query
The allows you to define your query without needing to learn CQL upfront.
You will need the Run query builder permission. If you are running queries on third-party integrations, you will also need the Run query builder with third-party integrations
x-cortex-circle-ci:
projects:
- projectSlug: circleci-projectslug # projectslug in CircleCI
alias: circleci-alias # alias is optional and only relevant if you have opted into multi account support
Report ID: Optionally, enter a Report ID to filter the list of employees.
We recommend entering a Report ID if you have a custom BambooHR Report that has the authoritative list of active employees.
This value can be found in the app URL, e.g., subdomain.bamboohr.comreports/custom/New+Hires/REPORTID
Employee ownership field: Optionally, enter the ownership field name.
If left blank, Cortex defaults to finding the list of employees using their division followed by their department.
https://cortex.circleci.com
How has deployment frequency changed over the last six months for the Platform team?
Deployment frequency serves as a proxy for both velocity and confidence. When you track this metric over time, you get clear evidence of whether your investments in tooling and process improvements are actually working. If deployment frequency is climbing, teams are shipping faster and feel confident doing it. If it's flat or declining despite investments, you need to investigate whether new tools are adding friction, whether processes are getting in the way, or whether something else is slowing teams down. The trend line tells you whether to double down on your current approach or change course.
This reveals whether AI adoption is actually delivering the productivity gains you expected. The comparison between adopters and non-adopters gives you a clear control group to measure impact. If teams using AI tools show meaningfully higher velocity, you have validation to expand the rollout and invest more.
If there's no significant difference, or if adopters are actually slower, you need to understand why. Maybe teams need better training on how to use the tools effectively. Maybe the tools work better for certain types of work than others. Maybe adoption is superficial and teams aren't integrating the tools into their actual workflows. The data points you toward the right interventions.
With this information, you can prioritize outreach based on service criticality. A critical payment service without a runbook demands immediate attention, while a lower-tier internal tool might wait. Instead of discovering documentation gaps during an active incident when every minute counts, you can systematically close them before they cost you hours of downtime.
Show me AI maturity Scorecard results across all teams. Where are the biggest gaps?
If you're driving AI adoption, this reveals which aspects of maturity need attention. The gaps tell you whether teams need training, tooling, process changes, or something else entirely.
Give me a plan to get the Checkout team back on track with production readiness.
Once you've identified a team falling behind, this generates a concrete action plan based on the specific gaps in their Scorecards and service metadata. You move straight to solutions.
Not all services are equally ready for incidents. This tells you whether runbooks exist, whether monitoring is in place, and whether escalation paths are documented. You know what tools you have before you need them.
When incidents happen, responders need clear guidance. This identifies documentation gaps that will slow response time before they cost you hours during an outage.
List all services with open vulnerabilities labeled CRITICAL or HIGH
This helps you quickly determine which services need attention.
Client ID and Client secret: Enter the client ID and secret you generated in the previous steps.
Click Save.
You will be redirected to the Azure Active Directory settings page in Cortex, where you can optionally set a group filter to limit which groups are pulled in from Entra ID.
Click Integrations from the main nav. Search for and select Apiiro.
Click Add configuration.
Configure the integration form:
Alias: Enter an alias for your configuration.
API key: Enter the API key you generated in Apiiro.
Host: Enter the base URL of your Apiiro instance. If left blank, the default host will be used.
Click Save.
After saving your configuration, you are redirected to the Apiiro integration settings page in Cortex. In the upper right corner of the page, click Test configuration to ensure Apiiro was configured properly.
How to connect Cortex entities to Apiiro
Discovery
Cortex uses the entity name, Cortex tag, or repository as the "best guess" for the corresponding Apiiro application. For example, if your entity name is "My Service" or your tag is my-service, then the corresponding application name in Apiiro should also be My Service or my-service.
If your Apiiro application names don’t cleanly match the Cortex entity name or tag, you can override this in the Cortex entity descriptor.
Editing the entity descriptor
You can define repositories and applications in the entity descriptor under the x-cortex-apiiro block:
Using the Apiiro integration
Viewing Apiiro risks on an entity
Entity page overview
On an entity details page overview, see risks listed under the Code & security block. Within this block, issues and vulnerabilities are grouped by severity: Critical, High, Medium, and Low. Click into any of these to open a list of all applicable issues and vulnerabilities.
Entity code & security sidebar
In an entity's sidebar, click Code & security > Apiiro to view risks from Apiiro.
Scorecards and CQL
With the Apiiro integration, you can create Scorecard rules and write CQL queries based on Apiiro risks.
List all risks for a given entity's Apiiro application.
Definition: apiiro.risks()
Example
A Scorecard's top level might include a rule to ensure that entities have a low number of Apiiro risks:
Check if Apiiro application is set
Check if entity has a registered Apiiro application in its entity descriptor.
Definition:apiiro ≠ null
Example
An initial level in a security Scorecard might include a rule to make sure entities are associated with an Apiiro application. Without this, Cortex won't pick up data about applications in Apiiro:
View integration logs
This feature is available to Cortex cloud customers.
The following options are available to get assistance from the Cortex Customer Engineering team:
Email: [email protected], or open a support ticket in the in app Resource Center
Slack: Users with a connected Slack channel will have a workflow added to their account. From here, you can either @CortexTechnicalSupport or add a :ticket: reaction to a question in Slack, and the team will respond directly.
Don’t have a Slack channel? Talk with your Customer Success Manager.
Click Integrations from the main nav. Search for and select LaunchDarkly.
Click Add configuration.
Configure the integration details:
Account alias: Enter the alias for this configuration.
Access token: Enter your LaunchDarkly access token.
Environment: Select your environment.
Click Save.
Configure the integration for multiple LaunchDarkly accounts
The LaunchDarkly integration has multi-account support. You can add a configuration for each additional organization, instance, or account by repeating the process above.
Each configuration requires an alias, which Cortex uses to correlate the designated organization, instance, or account with registrations for various entities. Registrations can also use a default configuration without a listed alias. You can edit aliases and default configurations from the LaunchDarkly page in your Cortex settings. Select the edit icon next to a given configuration and toggle Set as default on. If you only have one configuration, it will automatically be set as the default.
How to connect Cortex entities to LaunchDarkly
Discovery
By default, Cortex will try to "best-guess" the corresponding project in LaunchDarkly based on the key or tags.
Cortex first looks up a LaunchDarkly project using the entity name (e.g. My Service), then the entity identifier (e.g. my-service). For example, if your entity name is “My Service”, then the corresponding LaunchDarkly project's key or tag should contain either “My Service” or "my-service".
If no project was matched, Cortex will try to "best-guess" feature flags from all available projects using feature flag tags.
Editing the entity descriptor
You can find the project key and tags in LaunchDarkly under Account settings > Projects. The URL for the project will contain the key. For example: https://app.launchdarkly.com/projects/default/settings/environments.
If you prefer to use the project tags in the registration instead, you can find it in the projects table or project settings page.
Using the LaunchDarkly integration
Scorecards and CQL
With the LaunchDarkly integration, you can create Scorecard rules and write CQL queries based on LaunchDarkly projects.
Check if entity has a registered LaunchDarkly project in its entity descriptor. If no registration exists, we'll try to automatically detect which corresponding LaunchDarkly project is associated with the entity.
Definition: launchDarkly (==/!=) null
Example
For example, you could write a rule in a Scorecard to check whether an entity has a LaunchDarkly project set:
Feature flags
List of flags
Definition: launchDarkly.flags()
Example
In a Scorecard, you could write a rule to check whether an entity has fewer than 10 flags:
View integration logs
This feature is available to Cortex cloud customers.
The following options are available to get assistance from the Cortex Customer Engineering team:
Email: [email protected], or open a support ticket in the in app Resource Center
Slack: Users with a connected Slack channel will have a workflow added to their account. From here, you can either @CortexTechnicalSupport or add a :ticket: reaction to a question in Slack, and the team will respond directly.
Don’t have a Slack channel? Talk with your Customer Success Manager.
x-cortex-launch-darkly:
projects:
- key: project-key
environments: # Optional
- environmentName: prod
- environmentName: staging
alias: alias-1 # alias is optional and only relevant if you have opted into multi account support
- tag: project-tag
environments: # Optional
- environmentName: prod
alias: alias-2 # alias is optional and only relevant if you have opted into multi account support
feature-flags:
- tag: feature-flag-tag
environments: # Optional
- environmentName: staging
alias: alias-3 # alias is optional and only relevant if you have opted into multi account support
Identifier: This field is auto-populated based on your entity name. It is a unique identifier for your entity. This is also known as the x-cortex-tag.
Description: Enter a description of the entity to help others understand its purpose.
Owners: Define ownership for your entity. We recommend selecting team owners to keep your ownership information up-to-date through any future personnel changes.
Links: Add links to external documentation, such as runbooks, docs, logs, or custom categories.
Parents: Define parent domains. This is where you configure the hierarchy for your entity. These can be visualized in the relationship graph.
Dependencies: Select entities that this entity depends on. These can be visualized in the relationship graph.
On-call: Configure on-call information.
Repository: Select the repository associated with this entity.
Configure the form:
Type: Select Service.
Entity name: Enter a human readable name.
Identifier: This field is auto-populated based on your entity name. It is a unique identifier for your entity. This is also known as the x-cortex-tag.
Description: Enter a description of the entity to help others understand its purpose.
Groups: Select your entity.
Owners: Define ownership for your entity. We recommend selecting team owners to keep your ownership information up-to-date through any future personnel changes.
Links: Add links to external documentation, such as runbooks, docs, logs, or custom categories.
Parents: Define parent domains. This is where you configure the hierarchy for your entity. These can be visualized in the .
Dependencies: Select entities that this entity depends on. These can be visualized in the .
On-call: Configure on-call information.
Repository: Select the repository associated with this entity.
When you are finished, click Confirm import at the bottom of the page.
Example cortex.yaml for a service
Configure the integration form:
Alias: Enter an alias for the integration.
Username: Enter your Jenkins username.
API key: Enter your Jenkins API key.
Host: Enter the base URL of your Jenkins instance.
The token requires read permissions at minimum. This allows Cortex to automatically look up project tokens for each Rollbar project and attempt to reuse them to access project details.
Granting the token read and write permissions enables Cortex to automatically create an access token if none exists for a given project.
Click Integrations from the main nav. Search for and select Rollbar.
Click Add configuration.
Configure the integration form:
Account access token: Enter the access token you generated in Rollbar.
Account name: Enter your Rollbar account name, found in your Rollbar settings.
The name also appears in the URL for your Rollbar instance, e.g.,
Click Save.
After saving your configuration, you are redirected to the Rollbar integration settings page in Cortex. In the upper right corner of the page, click Test configuration to ensure Rollbar was configured properly.
How to connect Cortex entities to Rollbar projects
Discovery
By default, Cortex will use the Cortex tag (e.g. my-entity) as the "best guess" for Rollbar projects. For example, if your Cortex tag is my-entity, then the corresponding project in Rollbar should also be my-entity.
If your Rollbar projects don’t cleanly match the Cortex tag, you can override this in the Cortex entity descriptor.
Editing the entity descriptor
You can define projects under the x-cortex-rollbar block in an entity's YAML:
Field
Description
Required
project
Project name as defined in Rollbar
✓
Using the Rollbar integration
Viewing Rollbar errors on an entity
Error data from Rollbar will appear on an entity's details page. In an entity's sidebar, click Error tracking to view detected issues for each Rollbar project. At the top of the page, see the associated project tag and the project framework.
Under Items, see a list of detected errors and their statuses. Next to the error name, you can also see badges for # seen and the type of event: error, warning, or info.
Scorecards and CQL
With the Rollbar integration, you can create Scorecard rules and write CQL queries based on Rollbar projects.
The following options are available to get assistance from the Cortex Customer Engineering team:
Email: [email protected], or open a support ticket in the in app Resource Center
Slack: Users with a connected Slack channel will have a workflow added to their account. From here, you can either @CortexTechnicalSupport or add a :ticket: reaction to a question in Slack, and the team will respond directly.
Don’t have a Slack channel? Talk with your Customer Success Manager.
If using XML, configure the ID with the following permissions:
get Detailed report
get Build list
get sandbox list
get application list
If using REST, configure the ID with the following permissions:
get application
get findings
Create a with the following roles:
Creator or Security Lead
Reviewer or Security Lead
If you're using a self-hosted instance of Veracode, you'll need to verify that your Cortex instance is able to reach the Veracode instance.
We route our requests through a static IP address. Reach out to support at [email protected] to receive details about our static IP. If you're unable to directly allowlist our static IP, you can route requests through a secondary proxy in your network that has this IP allowlisted and have that proxy route traffic to your Veracode instance.
Click Integrations from the main nav. Search for and select Veracode.
Click Add configuration.
Configure the Veracode integration form:
Key ID: Enter your Veracode API ID.
Secret key: Enter the secret key associated with your API ID.
Region: Enter your Veracode instance .
Click Save.
Advanced configuration
If you’re unable to expose your Veracode instance to be reachable by Cortex, you can set up a custom integration webhook.
How to connect Cortex entities to Veracode
Editing the entity descriptor
You can set up the Veracode integration for an entity by specifying its Veracode application names or sandboxes in the x-cortex-static-analysis section of the entity descriptor. For example:
The application and sandbox names must appear exactly as they are in Veracode.
Using the Veracode integration
View Veracode data on entity pages
On an entity details page overview, Veracode findings will appear the Code and Security block.
When viewing an entity, click Code & security > Veracode to see the DAST findings count, SAST findings count, SCA findings count, and a list of findings that can be filtered by severity and source. The data syncs automatically every hour, or you can click Sync findings in the upper right side of the entity's Veracode page to trigger a sync.
Scorecards and CQL
With the Veracode integration, you can create Scorecard rules and write CQL queries based on Veracode findings.
The following options are available to get assistance from the Cortex Customer Engineering team:
Email: [email protected], or open a support ticket in the in app Resource Center
Slack: Users with a connected Slack channel will have a workflow added to their account. From here, you can either @CortexTechnicalSupport or add a :ticket: reaction to a question in Slack, and the team will respond directly.
Don’t have a Slack channel? Talk with your Customer Success Manager.
Any user can request an exemption. This can be done , or via the Cortex UI.
While viewing a Scorecard in the Cortex UI:
Click into an entity on which you want to request a rule exemption.
A side panel will open, showing each rule applied to that entity.
Next to the rule you want to request an exemption for, click the 3 dots icon, then click Request exemption.\
In the Request rule exemption side panel, configure the details: Choose whether you want to request a permanent exemption or enter how many days you want to exempt the entity from this rule, and optionally include a reason.
We recommend including a reason when you submit an exemption request. Requests will be reviewed by admins, and a clear explanation will help them determine whether an exemption makes sense.
If the Scorecard has user-specific notifications enabled, you'll need to select a user to notify of the rule exemption request. That user will be able to review, and approve or reject the request. If this field is not enabled, then all Admins will be notified of the request.
Permanent or time-bound exemptions
You’ll use a permanent exemption when there’s no expectation an entity will pass a rule, whereas a time-bound exemption makes more sense when an entity is expected to be in compliance with a given rule by a certain time.
In many cases, a time-bound exemption will be related to an ongoing Initiative. For example, entities might be required to have an on-call rotation set up by the end of the quarter. In this case, a developer may request an exemption that ends a few weeks before the quarter concludes — this can serve as a backup reminder if on-call isn’t set up at that point, and in the meantime, the failing rule won’t add any noise to the developer’s workflow.
When the time period for a temporary exemption elapses, any entities that are not in compliance with the rule would display as failing, while those in compliance would display as passing.
How to approve, deny, or revoke a rule exemption
To approve or deny rule exemptions, you must be an Admin, or you must have a custom role that contains the Configure Scorecard exemptionspermission.
If your Scorecard is configured to enable auto-approval for exemptions, then you do not need to take any action to approve the exemption.
After the user submits an exemption request, the exemption will appear in the Scorecard's Exemptions tab as Exempt, with the option to revoke the exemption appearing on the right side of the rule:
Also note that if you are an admin user and you request an exemption, it will automatically approve.
Manual approval
If you have notifications enabled for rule exemption requests, then you will receive a notification when a user requests an exemption. The notification includes the name of the requestor, the rule name and its Scorecard, the entity that the exemption applies to, the reason and timeframe provided by the requestor, and a direct link to approve or deny the request in Cortex.
If you do not have notifications enabled, you can view the exemption requests in Cortex (in Scorecard's Exemptions tab or under Settings > Scorecards > Rule exemptions) and then accept, reject, or revoke from there.
API
You can , , or a Scorecard rule exemption via the API.
View exempted rules
Admins, or users with the Configure Scorecard exemptionspermission, can view exemption requests, approve or deny the request, and revoke exemptions.
View exemptions in a Scorecard
When viewing a Scorecard, click into the Exemptions tab to view requests for exemptions and rules that have already been exempted:
In a Scorecard, entities are scored against rules. Rules can reference entities' metadata within Cortex, and can pull data from third-party integrations. Use levels and points in Scorecards to gamify the process and encourage developers to make progress toward goals.
While Scorecards do encourage teams to standardize entities, they do not have deadlines attached; if you have a goal that is more urgent or has a specific deadline, you can create an Initiative to promote progress by a certain date.
Common Scorecard use cases
See Scorecard examples for common use cases and to see how others are motivating their teams with Scorecards.
In the video below, learn how Scorecards, Initiatives, and Reports can be used together to drive business goals.
Creating, viewing, and editing Scorecards
Creating Scorecards
You can configure Scorecards directly in the Cortex UI, without needing to manage them solely through code. This makes it easier to get started, iterate over time, and involve more teammates without requiring deep context. If you prefer a GitOps approach, that's supported as well. See Scorecards as code for more information.
On this page, learn about viewing and editing Scorecards. For step by step instructions on creating Scorecards, see Creating a Scorecard. To learn about evaluating a Scorecard and mitigating failed rules, see Review and evaluate Scorecards.
Expand the tiles below to learn about viewing and editing Scorecards.
All of your organization’s Scorecards are listed under All. Under Mine, you’ll find Scorecards you’ve created, as well as Scorecards that evaluate entities you own.
Edit a Scorecard
Edit a Scorecard
If you have not disabled UI editing, then you can edit a Scorecard in the Cortex UI. You can edit the name, description, levels, rules, draft status, filter criteria, and the entity's being evaluated by the Scorecard. You cannot edit a Scorecard's unique identifier.
You must have the Edit Scorecard permission.
To edit:
Navigate to the Scorecard in Cortex.
Click Edit in the upper right corner of the Scorecard page:\
Make changes to your Scorecard, then at the bottom of the page, click Save Scorecard.
Any time you edit and save your Scorecard, Cortex will automatically begin reevaluating the relevant entities to reflect your changes.
Configuring global Scorecard settings
Admins can configure settings and view Scorecard rule exemptions under Settings > Scorecards.
Cortex offers a wide variety of out-of-the-box integrations compatible with Scorecard rules. Sometimes, a Scorecard may have multiple integration queries with different endpoints, each with its own rate limits. While we strive to manage these rate limits efficiently, please keep the following points in mind regarding rule failures and third-party integrations:
Are errors logged in the UI?
Yes, any errors will be displayed alongside the rule for the relevant entity in the UI.
Are the rules related to the errors retried?
If we encounter a rate limit error, we will retry the rule for most integrations. This process occurs up to five times with a backoff period between attempts. If the rule fails after five retries, the last recorded score will be used.
How are scores affected by missing values due to API rate limiting?
If all retries are still affected by rate limit errors, we will use the last known score for the rule. This also applies to 5xx errors from upstream APIs and any unexpected errors from the Cortex side. If a new rule fails without a previous score, the rule will fail and display a 429 error.
On the right side of the Query builder page, click the CQL builder tab. \
In the CQL builder, choose and integration and a rule to evaluate.
The rules available in the dropdown menu will depend on the integration you've selected.
Depending on the rule you choose, you may need to configure additional fields.
Click Use query. The query will automatically populate into the CQL text editor on the left side of the page.\
Step 2: Test the query
Under the CQL text editor on the left, select an entity to test the query against.
Click Test.
The results appear under the text editor. Review the results to verify that the query is working as you expect.
\
Step 3: Run the query
In the lower right corner of the page, click Run query.
In the side panel that opens, choose whether to run the query on all entities or select specific entities.
At the bottom of the side panel, click Run query.
In the confirmation modal that appears, click Yes, run query.
View and share results
After running the query, the page displays a list of all entities matching the criteria. In the upper right corner of the list, you can sort and filter the list. As you apply filters to your list, Cortex will also update the number of matching entities, so you can easily see at a glance how many entities match your requirements.
You can share the results in two ways:
Send a link: Click Share in the upper right corner of the results list to copy the URL to your clipboard. You can share the link with anyone who has access in your Cortex workspace.
Export as CSV: In the upper right corner of the page, click Export CSV to download a CSV file of the data.
Running rules on multiple queries
If you want to run a query on more than one rule, you can join multiple queries together with AND and OR.
For example:
CQL errors
The following errors may occur when running a CQL query:
400: This typically indicates a misconfiguration with an integration. For example, you may be missing an entity registration required for an integration.
403: This occurs if there are missing or improper permissions.
429: This occurs when hitting the rate limit for an integration. Cortex will retry 5 times before responding with this error. To prevent rate limit issues, we have built a self-throttling system that proactively throttles before hitting a rate limit from the vendor.
500: This indicates that the integration itself returned an error.
Save a query
While viewing the results of a query you ran, you can save the query to use again in the future:
In the upper right corner of the results page, click Save query.\
In the side panel, configure the query details:
Enter a name and description for your query.
To allow other users in your Cortex workspace to see the query, enable the toggle next to Share across organization.
Click Save.
View active, recent, and saved queries
Below the CQL search text box, you can see active queries. This section displays the ongoing process of your submitted query. When the query is complete, it will appear under Recent.
Along the top of the query builder, you can click into tabs to view Saved and Recent queries. Click into any of the queries in these lists to view the results of the query.
Saved queries
Click the Saved tab to view a list of your saved queries, and queries that others have saved and shared across your organization.
Query results are not automatically updated, but you can refresh a query manually: While viewing the results page, click the 3 dots icon, then click Refresh.
When configuring a CQL report, it is possible to enable automatic refresh.
Recent queries
Click the Recent tab. This list shows all queries that have been run in the last 30 days.
Domains offer a way to group entities into hierarchical units. You can group by product area, functionality, systems, business units, or something unique to your organization. With this feature, you can cluster entities into a single, hierarchical domain that can include both parents and children.
You can define a list of other entities as children for a domain, allowing you to represent a hierarchy of how your entities are modeled across your workspace. This hierarchy is available to view in the Domains catalog, on a domain entity's details page, and in the relationship graph. The domain hierarchy can also be used to configure ownership inheritance, helping you keep track of ownership in case of personnel changes at your organization.
Viewing domains
You can view all domains under Catalogs > Domains.
Display in hierarchy
To display domains in a hierarchy:
Click Display at the top of the domains list.
Enable to toggle next to Display hierarchy.
Click Done.
You can also view the hierarchy for a given domain on its . If the domain has parents or children, those will appear on the Relationships page.
In the entity's side bar, click Relationships, then click the Hierachy tab.
View in relationship graph
At the top of the domain, click View in domains tree to visualize your domain hierarchy in the .
Creating domains and a hierarchy
You can create domains:
By importing them from a connected integration
Manually in the Cortex UI
Via the entity descriptor YAML through
For simplicity, we recommend adding the highest-level domain first and then selecting it as the parent for subsequent domains. However, you can add parents and children to any domain at any point.
Importing domains
You can import domains directly from third-party integrations:
In Cortex, navigate to Catalogs > All entities, then click Import entities.
Choose Import discovered entities.
Edit domains
It is possible to edit entities after creating them:
Navigate to the entity's page.
In the upper right corner, click Configure entity.
Make any desired changes.
Adjusting domain settings
Under , you can enable automatic import of domains and domain relationships from .
Adding custom data
Custom data extends the out-of-the-box metadata that Cortex provides via integrations, enhancing your use of catalogs and augmenting details available for your entities. This data can also be used to write CQL queries and Scorecard rules.
Custom data can be defined manually in the entity descriptor, added to entities programmatically via a REST API, or sent through a webhook. To learn about sending data via webhook, see Custom webhook integrations.
Custom data should be used when you need to attach static or slowly changing metadata to entities, such as deployment environments, compliance statuses, or other descriptive attributes. It is best for enriching entity details, reporting, and Scorecard rules based on entity attributes. Learn more below in .
It is not ideal for tracking dynamic or time-sensitive information, as new data will overwrite previous values for the same key.
Custom metrics should be used to track time series or trending data, such as incident counts, SLOs, or any metric that changes over time and needs to be visualized in charts or analyzed in Eng Intelligence. Learn more in
Defining custom data
There are a few ways you can add custom data to an entity:
In the entity descriptor
This is optimal for low-volume, human-maintained data because it requires updating the entity's YAML when the data changes.
Via a POST REST API endpoint
Editing the entity descriptor
Learn more about in the Managing entities documentation.
The simplest way to describe information in the YAML is to define an object.
Field
Description
Required
Data source hierarchy
Cortex applies a data source hierarchy to determine how to handle a case where the same key is defined from multiple sources.
The is the source of truth. If a key is defined there, the API or webhooks cannot override the key.
The and approaches are at the same level and can override each other.
You can override keys defined in the YAML by adding a force=true parameter when using an API, but when the entity descriptor is eventually re-processed, the data provided via the API will be overwritten.
Use cases
Cataloging
Catalogs contain a lot of useful metadata about entities, including ownership and data from integrations. However, you may have your own custom fields that you want to include that would make exploring the catalog easier.
These can include things like:
Which AWS zones is this deployed in?
What databases does the entity consume?
When was the last successful CI run?
If the answers to these questions fit a pre-enumerated list, consider using . Groups are displayed on entity detail pages and can easily be applied in catalog filters.
Custom data for cataloging makes the most sense when the data is more flexible.
Custom data can then be queried against by using the , explored with , or viewed on an .
Scorecards
Cortex makes it easy to write based on custom data that exists in your catalogs. When adding a rule, you can select Custom data from Choose an integration in the form editor and follow the flow. Cortex will automatically supply variables based on the custom data you've defined.
Using the to push data into Cortex and extend your Scorecards. You can send entire JSON payloads and use jq to process them in a Scorecard, or use it as an input to a custom OPA Policy as a Scorecard rule.
Defining dependencies
In Cortex, you have the ability to define outgoing dependencies on other entities. Cortex can also automatically discover dependencies for some integrations. Having dependencies defined powers the ability to notify owners when a dependency deprecates its API or makes backwards incompatible changes, and the ability to visualize dependencies in a relationship graph.
Incoming dependencies are inferred based on the outgoing dependency definitions.
Visualize dependencies in the relationship graph
In Cortex, you can visualize dependencies using the relationship graph at Tools > Relationship graphs. See the for more information.
Automated dependency notifications
This feature is available in beta. Please reach out to your Cortex Customer Success Manager for access.
When a dependency deprecates its API or makes backwards incompatible changes, Cortex surfaces these issues via these methods:
Breaking API changes are listed in your Cortex workspace under .
Cortex attempts to automatically make comments on PRs containing breaking OpenAPI changes that have downstream dependencies that Cortex knows about.
If a breaking change is merged to the default branch, Cortex alerts dependency owners via Slack that a breaking change was merged.
Discovery
Cortex can automatically discover dependencies from your integrations:
How to define dependencies
You can define dependencies manually via an entity's YAML descriptor, via the Cortex UI (if UI editing is enabled), or via the API.
Your user or API key need the Edit entities permission.
Define dependencies in the Cortex UI
Navigate to the entity where you need to define a dependency.
In the upper right corner of the entity details page, click Configure entity.
Click the Hierarchy tab.
Sync dependencies
Cortex syncs AWS dependencies every day at 8:00 a.m. UTC. All other dependencies sync at 12:00 a.m. UTC.
You must have the Enable entity dependency discovery permission to manually sync dependencies.
If you need to sync dependencies manually:
Navigate to Tools > Relationship graphs.
In the upper right corner of the page, click the menu icon, then click Sync dependencies.
Troubleshooting and FAQ
What if I have multiple dependency sources?
When leveraging multiple dependency sources (such as Datadog and a catalog entity's YAML), all the sources will be merged together and deduplicated.
For example, if an entity YAML indicates X->Y and Datadog indicates X->Y and X->Z, we will have two edges presented (X->Y and X->Z).
Adding external documentation
Cortex is your source of truth to external docs. Instead of digging through wikis and other resources, you can aggregate docs on the relevant entities in Cortex in the following ways:
If you have configured the , you can use Slack Bot commands to .
View links on an entity
Links appear on an entity details page in the Links & docs section:
Add links to an entity
On entities, you can add links to docs, runbooks, tech specs, dashboards, and more.
Before editing an entity via the UI, make sure that UI editing is enabled under .
In Cortex, navigate to an entity.
In the upper right corner of the entity details page, click Configure entity.
Click Links on the left side.
You can quickly look up links using the .
Git-driven markdown docs
Cortex automatically embeds markdown files from the docs folder of your repo or from the root directory. If Cortex detects relevant files, these docs show up under the Links & docs page in an entity's sidebar.
Cortex uses the for rendering the documents.
Documentation types
When , Cortex supports embedding OpenAPI or AsyncAPI specs, embedding specs from your repository, adding relative links to a repository that isn't associated with the entity, and embedding charts (from Datadog, Grafana, New Relic, or other sources). You can also create a custom type while .
Cortex supports displaying Swagger/OpenAPI or AsyncAPI specs for each entity in the API explorer on an . You can also authorize your API and run queries directly in the API explorer.
OpenAPI docs
You can use your file as an OpenAPI spec file. As mentioned in the , the entity descriptor file extends the OpenAPI spec, so you can implement the spec directly in this file.
You may have existing or external specs you want to display in the API explorer from sources such as Swagger Hub or GitHub Raw URL. Add these to the JSON or YAML spec file under the block, with the type openapi.
Embed specs from a git repository
If you have specs checked into your git repository, you can embed it by adding it as a relative URL with type openapi. For example:
Relative links in another repo
In addition to providing the ability to link to specs within the service repo, Cortex also allows for links that reference other git repositories that aren't necessarily associated with your entity but still within your organization.
Power users can also specify a branch parameter between the second and the third colon separated group, in the form github:org/repo:branch:path/to/file. If this parameter is omitted, we will use the repository's default branch.
Relative link YAML examples
Adding OpenAPI via the Cortex API
Using your , you can also send your OpenAPI JSON or YAML file to the public /api/v1/catalog/documentation/openapi for each of your entities. One API doc per entity can be uploaded and it will automatically show up as an API Doc entry in the dropdown in the API explorer.
The request body is the following, in JSON format. See API Docs for authentication details.
Field
Type
Description
Converting YAML or JSON to string You can use a lightweight utility like jq to take your yaml/json and generate a string that can be used for your request:
e.g. $(cat my_file.yaml | jq -Rsa)
AsyncAPI docs
You may have existing or external specs you want to display in the API explorer from sources such as Swagger Hub or GitHub Raw URL. Add these to the JSON or YAML spec file under the block, with the type async_api.
If you have specs checked into your Git repository, you can embed it by adding it as a relative URL with type async_api. For example:
Embedded dashboards
Cortex supports embedding charts from , , or directly into an entity for quick access. To view embedded charts, click the Dashboard page in the .
You can add charts to an entity's YAML:
The type field is an optional enum of three types: datadog, grafana, or newrelic.
The url field is the src value for the iframe
Note that you can embed individual charts, not dashboards.
If you're using Grafana and seeing errors in your Grafana embeds, make sure your Grafana instance .
Embed content from other sources
It is possible to display content from a source other than Datadog, Grafana, or New Relic. To do this, do not specify an option for the type field. The URL you add must be publicly accessible or provide cross-platform authentication for Cortex to view and display the iframe. For example, if the content is accessible via VPN, then you should be able to view it in Cortex while on the VPN.
Accessing docs links via Slack
If you have configured the , you can use commands to list documentation directly in Slack:
/slack links <tag-or-id> to list all documentation links for an entity
/slack links [type] <tag-or-id> to list specific types of documentation links for an entity
The type corresponds to the type of documentation (e.g., openapi, documentation, etc.). Replace <tag-or-id> with the .
For example:
To list all documentation links for an entity with ID en29f044598b112345, you could run the following command in Slack:
/cortex links en29f044598b112345
To list the OpenAPI specs for an entity with tag plugin-extension, you could run the following command in Slack:
/cortex links openapi plugin-extension
The Slack Bot links command works for any docs links listed under x-cortex-links. Note that it does not list the listed under x-cortex-dashboards.
Managing Terraform infra in Cortex
Cortex Workflows can trigger Terraform execution to manage your cloud infrastructure, such as provisioning new services, databases, buckets, or networking primitives.
Terraform is an infrastructure-as-code tool that lets you provision, manage, and update infrastructure. Terraform can help you manage databases, s3 buckets, clusters, and every other component that comprises your infra. Terraform’s ability to manage resources comes from providers, which are plugins that enable interaction with cloud providers, SaaS providers, and other APIs. Providers allow you to define as code what a resource looks like.
The instructions on this page apply to Terraform Cloud, the web-based interface for Terraform.
Cortex integrates with Terraform in two different ways, depending on whether you want to manage Cortex resources using Terraform or use Cortex to drive Terraform runs for your infrastructure.
To learn about managing Cortex resources using Terraform, see .
How to manage Terraform infrastructure in Cortex
See end-to-end examples for , , and .
Prerequisite
Expand the tile below for instructions on provisioning a new instance.
Provision a new instance and update the instance name
Provision a new instance
Terraform will automatically provide you with a starter workspace when you begin — our example workspace is named "tfc-guide-example".
Step 1: Confirm your instance name update in Terraform
In Terraform Cloud, navigate to the Run page. Verify that the changes you made to the instance name in variables.tf have applied.
In Terraform, there are two primary commands: plan and apply.
The plan command creates a plan and preview of the changes that will be made to your infrastructure. During the plan stage, Terraform assesses the main.tf file with variables and compares it against the state. If there are differences, Terraform prompts you to approve and apply the change.
When you navigate to the run that was triggered by updating variables.tf, you can see that the plan was automatically conducted. In this case, the plan was to create an instance with the name provided earlier. Verify that the run displays a "Plan finished" message.
In AWS, you can confirm that the instance exists and that the Terraform action was successful:
In this example, we made direct modifications to the main branch, but typically, you will edit a separate branch and create a pull request. This approach will run a plan in Terraform, but will not automatically apply changes.
Step 2: Add the Terraform template in Cortex
Cortex not only integrates with Terraform, but can enhance your use of it. Once the integration is set up, you’ll use a to interact with Terraform.
You must have the Configure Scaffolder templates permission.
When using the Scaffolder, it's best to edit a secondary branch and create a pull request — the Scaffolder will actually create the pull request for you, which someone else can approve to apply the changes.
Create a JSON file that is equivalent to your Terraform module.
In this file, we defined the region and instance name. You’ll then update the fields in the variables.tf file so it knows to pull information from the Cookiecutter JSON.
in Cortex.
Verify that the process worked
Verify the process
To verify that the process worked, open Terraform Cloud and navigate to Runs.
Any runs that originate from Cortex will have [Cortex Scaffolder] at the start of their name. Click into one of these runs to see its status and how many changes were proposed.
Execute a run via a Workflow
Terraform Cloud also has an API that can be used to make updates without following the pull request workflow. You can use a in Cortex to execute a run through the API. If a run is set to automatically apply, then Cortex will handle the rest of the process.
in Cortex.
Add a block.
Define inputs for Instance name, Region, and Instance type
When the Workflow is run in Cortex, it will override data in the variables.tf file with information that was entered in the fields.
Verify the run
Verify that the action was successful
In Terraform Cloud, you can verify that the action was successful and the run was queued. Runs triggered by actions are named "Triggered via API."
Once the run has been applied, you can also verify it in AWS. In the example screen shot below, the instance name has been changed:
Terraform Workflow examples
See guides on creating the following Workflows: , , and .
ArgoCD
ArgoCD is a declarative, GitOps continuous delivery tool for Kubernetes.
To send Cortex information about syncs in ArgoCD, use ArgoCD notification to call the Cortex .
Example config map
Here is an example of what a argocd-notifications-cm config map may look like:
This example assumes your ArgoCD application's name matches the x-cortex-tag. In this case, each application in ArgoCD can subscribe to the same trigger.
If your application name doesn't match the x-cortex-tag, add a value/pair to the info section of the Application manifest. Then, instead of using .app.metadata.name in the url, use .app.spec.info[0].value.
Step 2: Subscribe application to webhooks
Next, subscribe your application to the webhook. You do this by adding a label annotation in the Application spec in the following format:
For example, if we want to subscribe an application to the example webhook above, the Application YAML may look like the following example:
Using the ArgoCD integration
View ArgoCD data on entity pages
After you configure the integration, you will see data about ArgoCD syncs in an :
On the entity overview, ArgoCD syncs will appear under the Latest events section.\
In the entity's sidebar, click Events to see a full list of events for the entity, including sync events from ArgoCD.
In the entity's sidebar, click CI/CD > Deploys to see data from the , including ArgoCD syncs.\
Automate ArgoCD events in Workflows
You can use a Workflow to automate ArgoCD syncs. .
See ArgoCD data in Eng Intelligence
Since the ArgoCD integration uses Cortex's , ArgoCD data is included in Eng Intelligence deploy metrics. Learn more about .
Troubleshooting and FAQ
What permissions does my API Key need?
The API key needs to be able to call the API endpoint, so ensure the Edit entities permission is enabled.
Ensure the Cortex API Key is encoded correctly
Make sure the encoded Cortex API Key does not contain an extra line. Use a tool like https://www.base64encode.org/ to ensure your encoded key does not contain an extra line.
Check the ArgoCD logs
The notification webhook is managed by the argocd-notifications-controller which will have a pod running in your ArgoCD namespace.
Assuming the ArgoCD is running in the argocd namepsace, run the following command to get the list of pods:
kubectl get pods -n argocd
This will return a list of pods similar to the ones listed below:
In this example, the pod managing the webhook notifications is argocd-notifications-controller-6cd988b564-sql55. To get the logs, run the following command:
If your trigger was successful, you should seem something similar to this:
Still need help?
The following options are available to get assistance from the Cortex Customer Engineering team:
Email: , or open a support ticket in the in app Resource Center
Slack: Users with a connected Slack channel will have a workflow added to their account. From here, you can either @CortexTechnicalSupport or add a :ticket: reaction to a question in Slack, and the team will respond directly.
Don’t have a Slack channel? Talk with your Customer Success Manager.
Azure Resources
Azure Resources provides on-demand cloud computing platforms and APIs. Cortex uses the Azure Resource API to pull in resource details and import entities such as SQL servers, virtual machines, virtual networks, load balancers, and others.
Integrating Azure Resources with Cortex allows you to:
Create Scorecards to drive alignment and track progress on projects involving resources from Azure
How to configure Azure Resources with Cortex
Prerequisites
Before getting started, you will need the following information. These can be found in the Enterprise applications section of Azure:
Azure tenant ID
Azure client ID and
Azure subscription ID
Configure the integration in Cortex
In Cortex, navigate to the .
Click Integrations from the main nav. Search for and select Azure Resources.
Click Add configuration.
After saving your configuration, you are redirected to the integration settings page in Cortex. In the upper right corner of the page, click Test configuration to ensure Azure Resources was configured properly.
How to connect Cortex Entities to Azure Resources
For Azure Resources, Cortex replaces non-alphanumeric characters in entity names with a space. For example, resource_1 would become resource 1.
For the , Cortex replaces non-alphanumeric characters with - and lowercases the letters. If multiple special characters appear together in a tag, Cortex replaces the group of characters with only one -. For example, mY_e%ntity#$_tag would become my-e-ntity-tag
Enable automatic discovery of Azure Resource entities
You can configure automatic import from Azure:
In Cortex, navigate to the .
Next to Auto import from AWS, Azure, and/or Google Cloud, click the toggle to enable the import.\
Discover ownership for Azure Resources
Cortex can automatically discover ownership for your Azure resources. To configure this:
Make sure that your Azure resources have a tag matching the x-cortex-tag of the corresponding Cortex team
Enable the “Sync ownership from Azure” toggle in the in Cortex.
By default, Cortex looks for the owner
Cortex syncs ownership from Azure Resources every day at 6 a.m. UTC.
Define a dependency
Cortex automatically discovers dependencies between your services and resources by scanning for resources with specific Azure Resources tags. By default, a service will have dependencies on any Cortex resource that has a corresponding Azure Resources resource with Azure Resources tag key = "service" and tag value = the service's Cortex tag.
On the , you can customize the tag key names for dependencies.
For more information on defining dependencies, please see the .
Import entities from Azure Resources
See the for instructions on importing entities.
Editing the entity descriptor
You can associate a Cortex entity with one or more Azure Resources entities. Cortex will display those Azure Resources entities' metadata on the Cortex entity page.
When the entity is connected to Azure, the entity YAML will look like the following:
Using the Azure Resources integrations
Scorecards and CQL
With the Azure Resources integration, you can create Scorecard rules and write CQL queries based on Azure Resources details.
See more examples in the in Cortex.
Get Azure Resource details for entity
Get Azure Resource details for an entity.
Definition:azureResource.details(): Object
Examples
In a Scorecard, you can write a rule to make sure an entity has Azure Resource details:
Make sure an entity has an environment tag:
View integration logs
This feature is available to Cortex cloud customers.
On the integration settings page, click the Logs tab to view logs from the last 7 days. Learn more in .
Background sync
Cortex conducts a background sync of Azure Resources every day at 00:00 a.m. UTC and an ownership sync every day at 6 a.m. UTC.
FAQs and troubleshooting
Why is the Azure resource type microsoft-resources-subscriptions-resourcegroups not pulling in Azure Resource details?
Cortex pulls from the Azure Resource API, but not from the Azure Resource Group API. If you would like to submit a feature request for support of Azure Resource Groups, please contact our customer engineering team.
Still need help?
The following options are available to get assistance from the Cortex Customer Engineering team:
Email: , or open a support ticket in the in app Resource Center
Slack: Users with a connected Slack channel will have a workflow added to their account. From here, you can either @CortexTechnicalSupport or add a :ticket: reaction to a question in Slack, and the team will respond directly.
Don’t have a Slack channel? Talk with your Customer Success Manager.
Buildkite
Buildkite is a continuous integration and delivery platform that enablers users to run fast, secure, and scalable pipelines on their own infrastructure.
Integrating Buildkite with Cortex allows you to:
Pull in metrics about your builds and pipelines
Create Scorecards that track progress and drive alignment on projects involving your Buildkite pipelines
How to configure Buildkite with Cortex
Prerequisites
Before getting started:
Create a with read-only permissions for pipelines and builds.
You must be a member of a Buildkite organization to generate and use an access token for it.
Configure the integration in Cortex
In Cortex, navigate to the .
Click Integrations from the main nav. Search for and select Buildkite.
Configure the Buildkite integration form:
How to connect Cortex entities to Buildkite
Discovery
By default, Cortex will use the (e.g. my-entity) for your Buildkite pipeline. For example, if your Cortex tag is my-pipeline, then the corresponding pipeline tag in Buildkite should also be my-pipeline.
Cortex will also use the the GitHub, GitLab, Bitbucket, or Azure DevOps repository to connect entities to Buildkite pipelines. For example, if the GitHub repo associated with your Buildkite pipeline is my-org/repo, then entities in Cortex that also live in my-org/repo will populate with details from that pipeline.
Editing the entity descriptor
You can add Buildkite pipelines to an entity by defining the pipeline slug or tags with one of the following blocks in the entity descriptor:
Field
Description
Required
Field
Description
Required
The slug for your pipeline can be found in the Buildkite URL for a given pipeline (e.g., https://buildkite.com//).
Using the Buildkite integration
Entity pages
Once the Buildkite integration is established, Cortex will automatically pull in pipeline data to an entity's page. You can access this data from the CI/CD page in the entity's side panel.
You can find a list of pipeline runs for each pipeline linked to a given entity on this page:
Pipeline slug/tag
Action (e.g. "scheduled build")
Timestamp
Branch
The for a build will appear as a tag next to the pipeline slug/tag (e.g. canceled, passed, or failed).
Scorecards and CQL
With the Buildkite integration, you can create Scorecard rules and write CQL queries based on Buildkite pipelines.
See more examples in the in Cortex.
Check if Buildkite pipeline(s) are set
Check if entity has registered Buildkite pipelines in its entity descriptor.
Definition:buildkite (==/!=) null
Example
For a Scorecard focused on production readiness, you can pull in data from Buildkite to make sure that entities belong to a CI/CD pipeline.
Get Buildkite build(s)
Gets pipelines and builds that meet given filter criteria.
Build criteria:
Branch
Get Buildkite pipelines
Get all Buildkite pipelines associated with the entity: Description, Git repository, ID, Name, Slug, Tags.
Definition: buildkite.pipelines()
Example
A production readiness Scorecard can use this expression in a rule confirming that there are pipelines linked to a specific repository:
View integration logs
This feature is available to Cortex cloud customers.
On the integration settings page, click the Logs tab to view logs from the last 7 days. Learn more in .
Still need help?
The following options are available to get assistance from the Cortex Customer Engineering team:
Email: , or open a support ticket in the in app Resource Center
Slack: Users with a connected Slack channel will have a workflow added to their account. From here, you can either @CortexTechnicalSupport or add a :ticket: reaction to a question in Slack, and the team will respond directly.
Don’t have a Slack channel? Talk with your Customer Success Manager.
Custom webhook integrations
Custom webhook integrations allow you to POST data to a unique endpoint in Cortex, map the payload to existing entities, and make that data available for use in Scorecards, CQL queries, and on entity detail pages.
Using a custom webhook is especially helpful if:
You have internal tools, homegrown systems, or third-party services that Cortex doesn't integrate with yet.
You want to automate the process of sending custom metrics, events, or other data into Cortex without building and maintaining additional infrastructure.
You want to pre-process data before it reaches Cortex, such as adding extra metadata or transforming the payload format.
This can be done without auth or an explicit in the URL if you do not have access to the Cortex tag or the ability to add authentication headers.
You can also add custom metadata manually to an entity descriptor or programmatically via the API. Learn more in .
Below the instructions, see an example demonstrating how to .
How to create a custom webhook integration in Cortex
Step 1: Configure the custom integration in Cortex
In Cortex, navigate to Integrations. On the left side of the Integrations page, click .
Click +Add custom integration.\
Configure the integration details:
Step 2: Send data to the webhook
Note that the entity must exist in Cortex before you send the payload.
cURL is a quick and flexible method to post to the webhook and verify that it's receiving data.
Save your payload as a .json file. Include the field that matches the JQ expression configured in the previous steps, so Cortex can map the data to the correct entity.
For example, the payload might look like this:
In your terminal, use cURL to POST the JSON, using a command similar to the following:
curl -X POST -H "Content-Type: application/json" --data <path to json file> <webhook URL>
For example: curl -X POST -H "Content-Type: application/json" --data @/tmp/payload.json https://api.getcortexapp.com/api/v1/custom-integrations/data/12345abcdef
After sending data, the JSON payload is written to the entity's key that you configured for the custom webhook in .
Changing the mappings for entities
If the webhook payload does not contain a value that maps to the exact , you can configure alternative mappings to look up when processing payloads. Use the x-cortex-custom-integration-mappings block in the . For example:
When processing a payload, Cortex takes the output of the Entity tag JQ field in Step 1 above and searches for an entity with that value as a Cortex tag. If no such entity exists, Cortex checks whether an entity has registered the value as an alternative mapping; if so, the payload is attached to that entity.
View custom integration data in Cortex
Similar to when you , custom integration data appears in the sidebar on an within the Custom data & metrics page. It appears with an INTEGRATION tag next to the key name.
Example: GitHub webhook
In this example, we create a webhook integration to send GitHub data into Cortex.
While Cortex does offer a native integration with , there may be scenarios where you want to send additional metadata that isn't included in the native integration.
in Cortex.
Enter a descriptive name so others understand the purpose of this webhook, such as "GitHub metadata."
In this example, we use the Service query.repository.name and the KeygithubTest
Dynatrace
Overview
Dynatrace is a monitoring and observability platform. Integrate Dynatrace with Cortex to get insights into application performance, service discovery, SLOs, and dependencies.
How to configure Dynatrace with Cortex
Prerequisite
Before getting started, generate an with the scopes Read entities and Read SLO.
Configure the integration in Cortex
In Cortex, navigate to the .
Click Integrations from the main nav. Search for and select Dynatrace.
Click Add configuration.
If you’ve set everything up correctly, you’ll see the option to Remove Integration in settings.
You can also use the Test configuration button to confirm that the configuration was successful. If your configuration is valid, you’ll see a banner that says “Configuration is valid. If you see issues, please see documentation or reach out to Cortex support.”
How to connect Cortex entities to Dynatrace
Import entities from Dynatrace
See the for instructions on importing entities.
Editing the entity Entity descriptor
Entity ID
Entities with a type of "SERVICE" will be discovered and surfaced. When using the Dynatrace portal, service IDs can be found in the URL of a selected service under the id query param. For example, https://.live.dynatrace.com/#newservices/serviceOverview;id=
Entity name
You can also match entities based on matching with a regular expression, like:
Linking SLOs in Cortex
Dynatrace supports service-level objective (SLO) monitoring. You can link these SLOs to your Dynatrace entity in Cortex:
In Dynatrace, navigate to the Service-Level Objectives app.
On the left sidebar of Dynatrace, click Search, then type in slo to find the app.
On the SLOs page, see the list of SLOs. On the right side of an SLO, click ^ to expand the Details.
At the bottom of the page, click Save.
After saving, navigate back to your service details page to view the SLO status in the service's Overview tab.
For information on working with SLOs in Dynatrace, see .
Dependencies
Cortex automatically syncs from Dynatrace using attributes inherent to each entity.
Discovery audit
Cortex will pull recent changes from your Dynatrace instance into the . Here, you can find new entities in Dynatrace that have not been imported into the catalog - these will have the tag New APM resource - as well as entities in the catalog that no longer exist in Dynatrace - these will have the tag APM resource not detected.
Using the Dynatrace integration
Entity pages
With the Dynatrace integration, you'll see SLOs on an entity's home page. High-level information about SLOs appears in the Overview tab.
Click Monitoring in the entity's sidebar to see more detailed data: the SLO name, its target, the current value for that entity, and the period of time the SLO is being calculated for. For example, if the time listed is "7 days ago," then the SLO is looking at the time range starting 7 days ago to now.
Relationship graphs
detected from Dynatrace will appear in .
Scorecards and CQL
With the Dynatrace integration, you can create Scorecard rules and write CQL queries based on Dynatrace SLOs.
See more examples in the in Cortex.
SLOs
SLOs associated with a given entity via ID or tags. You can use these data to check whether an entity has SLOs associated with it and if those SLOs are passing.
History
ID
View integration logs
This feature is available to Cortex cloud customers.
On the integration settings page, click the Logs tab to view logs from the last 7 days. Learn more in .
Background sync
Cortex conducts a background sync of Dynatrace entities at 7 a.m. UTC and a dependency sync every day at 12 a.m. UTC. You can via the Relationship Graph.
FireHydrant
FireHydrant is an incident management platform that emphasizes reliability and consistency across the entire incident response lifecycle.
Integrating FireHydrant with Cortex allows you to:
Create to set standards around incident management and production readiness
How to integrate FireHydrant with Cortex
Prerequisites
Before getting started:
Create a .
Configure the integration in Cortex
In Cortex, navigate to the :
Click Integrations from the main nav. Search for and select FireHydrant.
Click Add configuration.
How to connect Cortex entities to FireHyrant projects
Editing the entity descriptor
You can define FireHydrant services in an .
For a given entity, define FireHydrant services by ID or slug. Each of these has the same field definitions.
Field
Description
Required
You can find the service ID value in FireHydrant under FireHydrant > Catalog > Services. The URL for the service will also contain the ID (e.g., https://app.firehydrant.io/catalog/services/{ID}/incidents).
If you prefer to use the service slug in the registration instead, you can find it on the right-hand side of the service page in FireHydrant.
Using the FireHydrant integration
Viewing FireHydrant incidents on an entity
When active incidents are detected in FireHydrant, Cortex will display incident information on an .
Click On-call & incidents in the entity's sidebar to see all detected incidents.
Each issue will be listed with its title and description (when available). Cortex will also display the status for an issue as a badge next to its name:
Acknowledged
Closed
Detected
The issue's severity will also appear in a badge (e.g. SEV0, SEV1, SEV2).
Trigger an incident
While viewing an entity in Cortex, you can trigger an incident in FireHydrant:
In Cortex, navigate to an entity. On the left side of an entity details page, click On-call & incidents.
In the upper right side of the entity's "On-call" page, click Trigger incident.
Configure the incident modal:
Scorecards and CQL
With the FireHydrant integration, you can create Scorecard rules and write CQL queries based on FireHydrant incidents.
See more examples in the in Cortex.
Check if FireHydrant service is set
Check if entity has a registered FireHydrant service in its entity descriptor. If no registration exists, we'll try to automatically detect which corresponding FireHydrant service is associated with the entity.
Definition:firehydrant (==/!=) null
Example
For a Scorecard focused an production readiness, you can use this expression to make sure a FireHydrant service - and thus incident response - is defined for entities:
Incidents
List of incidents, filterable on severity and status.
Created at
Description
View integration logs
This feature is available to Cortex cloud customers.
On the integration settings page, click the Logs tab to view logs from the last 7 days. Learn more in .
Still need help?
The following options are available to get assistance from the Cortex Customer Engineering team:
Email: , or open a support ticket in the in app Resource Center
Slack: Users with a connected Slack channel will have a workflow added to their account. From here, you can either @CortexTechnicalSupport or add a :ticket: reaction to a question in Slack, and the team will respond directly.
Don’t have a Slack channel? Talk with your Customer Success Manager.
Mend
Overview
Mend is an automated application security and remediation platform. Integrate Cortex with Mend to drive insights into potential vulnerabilities in your code and your third-party libraries.
Cortex supports integrating with:
: This product scans for vulnerabilities in the code you write.
: This product scans for vulnerabilities in your third-party libraries.
How to configure Mend with Cortex
See the tabs below for instructions on configuring Mend SAST and Mend SCA.
Prerequisite
Before getting started, .
If you're using a self-hosted instance of Mend, you'll need to verify that your Cortex instance is able to reach the Mend instance.
We route our requests through a static IP address. Reach out to support at to receive details about our static IP. If you're unable to directly allowlist our static IP, you can route requests through a secondary proxy in your network that has this IP allowlisted and have that proxy route traffic to your Mend instance.
Configure the integration in Cortex
In Cortex, navigate to the :
Advanced configuration
If you’re unable to expose your Mend instance to be reachable by Cortex, you can set up a Custom Integration Webhook.
How to connect Cortex entities to Mend
Discovery
By default, Cortex will use your associated Git repository (e.g. repo-name) as the "best guess" for the Mend SAST application name and the Mend SCA project name.
If your repository names don’t cleanly match the Mend SAST application names or Mend SCA project names, you can override this in the Cortex Service Descriptor.
Editing the entity descriptor
The application IDs can be found in the Mend SAST web interface.
A project ID can be found in the Mend SCA web interface; while viewing the project, the ID appears in the URL after project;id=.
Using the Mend integration
Entity pages
From the Overview tab on an entity page, you can find vulnerabilities in the Code and Security block.
In the left sidebar of an entity, click Code & security > Mend to view the total number of vulnerabilities, a risk score, and a list of vulnerabilities including the risk rating and creation date.
Scorecards and CQL
With the Mend integration, you can create Scorecard rules and write CQL queries based on Mend projects and applications.
See more examples in the in Cortex.
Check if Mend project is set
Check if entity has a registered Mend project
Definition:mend (==/!= null): Boolean
Examples
In a Scorecard, you can write a rule to make sure an entity has a Mend project set:
Vulnerabilities
List of vulnerabilities, filterable on risk and source
Definition:mend.vulnerabilities(): List
Examples
In a Scorecard, you can write a rule to make sure an entity has fewer than 10 vulnerabilities from both SAST and SCA sources:
You can write a rule to make sure an entity has fewer than 3 vulnerabilities with a risk level of "Medium" or "High":
View integration logs
This feature is available to Cortex cloud customers.
On the integration settings page, click the Logs tab to view logs from the last 7 days. Learn more in .
Still need help?
The following options are available to get assistance from the Cortex Customer Engineering team:
Email: , or open a support ticket in the in app Resource Center
Slack: Users with a connected Slack channel will have a workflow added to their account. From here, you can either @CortexTechnicalSupport or add a :ticket: reaction to a question in Slack, and the team will respond directly.
Don’t have a Slack channel? Talk with your Customer Success Manager.
Splunk On-Call (VictorOps)
Splunk On-Call (formerly known as VictorOps) is an alert and on-call management platform.
Integrating Cortex with Splunk On-Call allows you to:
Pull in on-call rotation data and escalation policies
The on-call user or team will appear in the Current On-call block on an entity's details page.
You can also view on-call information on an entity page in its side panel under Integrations > On-call.
Create that track progress and drive alignment on projects involving your on-call schedule
How to configure Splunk On-Call with Cortex
Prerequisites
Before getting started:
Create a .
Note: If the key is granted Read-only permissions, Cortex will only perform GET requests.
Obtain your Splunk API ID.
Configure the integration in Cortex
In Cortex, navigate to the :
Click Integrations from the main nav. Search for and select Splunk On-call.
Click Add configuration.
How to connect Cortex entities to Splunk On-Call
Editing the entity descriptor
With the Splunk On-Call integration, you can tie on-call rotations to entities under the x-cortex-oncall block with your schedule metadata. You can use the team ID, or you can filter beyond the team ID and use the policy ID. Using the policy ID is helpful if your team has multiple policies available.
Team ID in entity descriptor:
Policy ID in entity descriptor:
Field
Description
Required
You can find the team ID in the Splunk On-Call portal on the teams page (e.g., https://portal.victorops.com/dash/cortex-app#/team//users).
Using the Splunk On-Call integration
Entity pages
Once a Splunk On-Call schedule is defined in an entity descriptor, the user or team who is on call will appear in the Current On-call block on that .
You can also find on-call information for a given entity on the On-call & incidents page in the entity's sidebar.
Scorecards and CQL
With the Splunk On-Call integration, you can create Scorecard rules and write CQL queries based on Splunk On-Call schedules.
See more examples in the in Cortex.
Check if on-call is set
Check if entity has a registered team.
Definition:oncall (==/!=) null
Example
For a Scorecard focused an production readiness, you can use this expression to make sure on-call is defined for entities:
This rule will pass if an entity has a service, schedule, or escalation policy set.
Number of escalations
Number of escalation tiers in escalation policy.
Definition:oncall.numOfEscalations()
Example
This expression could be used in a Scorecard focused on production readiness or service maturity:
This rule checks that there are at least two tiers in an escalation policy for a given entity, so that if the first on-call does not ack, there is a backup.
On-call metadata
On-call metadata, including type, ID, and name.
Definition:oncall.details()
Example
You can use this expression in the Query builder to find all entities with an on-call rotation that includes a specific team. Let's say we want to find all entities that the "Sample Team" team is on-call for and the team's ID in Splunk On-Call is sample-team1234. Our query would then be:
View integration logs
This feature is available to Cortex cloud customers.
On the integration settings page, click the Logs tab to view logs from the last 7 days. Learn more in .
Still need help?
The following options are available to get assistance from the Cortex Customer Engineering team:
Email: , or open a support ticket in the in app Resource Center
Slack: Users with a connected Slack channel will have a workflow added to their account. From here, you can either @CortexTechnicalSupport or add a :ticket: reaction to a question in Slack, and the team will respond directly.
Don’t have a Slack channel? Talk with your Customer Success Manager.
Splunk Observability Cloud (SignalFx)
Splunk Observability Cloud (formerly known as SignalFx) is a monitoring and analytics platform that allows customers to evaluate, visualize, automate, and alert on metrics.
Integrating Splunk Observability Cloud with Cortex allows you to:
Create Scorecards that include rules related to your Splunk Observability Cloud SLOs
How to configure Splunk Observability Cloud with Cortex
Prerequisites
Before getting started:
Create an in Splunk.
Configure the integration in Cortex
In Cortex, navigate to the :
Click Integrations from the main nav. Search for and select Splunk Observability.
Click Add configuration.
After saving your configuration, you are redirected to the Splunk Observability integration settings page in Cortex. In the upper right corner of the page, click Test configuration to ensure Splunk Observability was configured properly.
How to connect Cortex entities to Splunk Observability SLOs
Editing the entity descriptor
SLOs can be defined in the .
You can pull in data about SLOs and manage them in Cortex by defining relevant SLIs through queries, along with a threshold and a comparator. Cortex will pull data from Splunk Observability Cloud and roll up the query with a specified rollup function.
Field
Description
Required
Using the Splunk Observability integration
Viewing SLO information on an entity
When an SLO is defined in an entity's descriptor, SLO information appears in the Monitoring block on an overview.
Monitoring
Click Monitoring > Data overview in the entity's sidebar to see the query, target, and current value for each SLO from any integrations you're pulling SLOs from. Each SLO also includes the period of time the SLO is being calculated for. For example, if the time listed is "7 days ago," then the SLO is looking at the time range starting 7 days ago to now.\
Click Monitoring > Splunk Observability to view a graph of SLO performance over time.\
Scorecards and CQL
With the Splunk Observability Cloud integration, you can create Scorecard rules and write CQL queries based on Splunk Observability Cloud SLOs.
See more examples in the in Cortex.
SLOs
SLOs associated with the entity via ID or tags. You can use this data to check whether an entity has SLOs associated with it, and if those SLOs are passing.
Definition:slos: List<SLO>
Example
In a Scorecard, you can use this expression to make sure an entity is passing its SLOs:
Use this expression to make sure latency Service Level Indicator (SLI) value is above 99.99%:
View integration logs
This feature is available to Cortex cloud customers.
On the integration settings page, click the Logs tab to view logs from the last 7 days. Learn more in .
Still need help?
The following options are available to get assistance from the Cortex Customer Engineering team:
Email: , or open a support ticket in the in app Resource Center
Slack: Users with a connected Slack channel will have a workflow added to their account. From here, you can either @CortexTechnicalSupport or add a :ticket: reaction to a question in Slack, and the team will respond directly.
Don’t have a Slack channel? Talk with your Customer Success Manager.
Pull in on-call rotation data and escalation policies
The on-call user or team will appear in the Current On-call block on an entity's details page.
You can also view on-call information on an entity page in its side panel under Integrations > On-call.
Trigger xMatters incidents from Cortex
Create that track progress and drive alignment on projects involving your xMatters services
How to configure xMatters with Cortex
Configure the integration in Cortex
In Cortex, navigate to the :
Click Integrations from the main nav. Search for and select xMatters.
Click Add configuration.
Trigger an incident
While viewing an entity in Cortex, you can trigger an incident in xMatters:
In Cortex, navigate to an entity. On the left side of an entity details page, click On-call & incidents.
In the upper right side of the entity's "On-call" page, click Trigger incident.
Configure the incident modal:
How to connect Cortex entities to xMatters
Discovery
By default, Cortex will use the (e.g. my-entity) as the "best guess" for xMatters group. For example, if your Cortex tag is my-entity, then the corresponding group in xMatters should also be my-entity.
If your xMatters group don’t cleanly match the Cortex tag, you can override this in the Cortex entity descriptor.
Editing the entity descriptor
Field
Description
Required
Using the xMatters integration
Entity pages
Once the integration with xMatters is configured, you'll be able to find the user or team on call in the Current On-call block on an .
You can find more detailed information from the xMatters integration in the entity sidebar under On-call & incidents > xMatters.
The schedule associated with a given entity will be hyperlinked in the Escalation Policy block and the group will be hyperlinked in the Service block.
Under the Escalations section, you'll find each level associated with the policy. Owners assigned to each level will also be hyperlinked to the user or team's on-call page in xMatters.
Scorecards and CQL
With the xMatters integration, you can create Scorecard rules and write CQL queries based on xMatters services.
See more examples in the in Cortex.
Check if on-call is set
Check if entity has a registered group.
Definition:oncall (==/!=) null
Example
For a Scorecard focused an production readiness, you can use this expression to make sure on-call is defined for entities:
This rule will pass if an entity has an on-call schedule set.
Number of escalations
Number of escalation tiers in escalation policy.
Definition:oncall.numOfEscalations()
Example
This expression could be used in a Scorecard focused on production readiness or service maturity. For example, you can check that there are at least two tiers in an escalation policy for a given entity, so that if the first on-call does not ack, there is a backup:
On-call metadata
On-call metadata, including type, ID, and name.
Definition:oncall.details()
Example
You can use this expression in the Query builder to find all entities with an on-call rotation associated with a given group. Let's say we want to find all entities that the "Sample team" is on-call for.
Because the team/group name is registered in the
View integration logs
This feature is available to Cortex cloud customers.
On the integration settings page, click the Logs tab to view logs from the last 7 days. Learn more in .
Still need help?
The following options are available to get assistance from the Cortex Customer Engineering team:
Email: , or open a support ticket in the in app Resource Center
Slack: Users with a connected Slack channel will have a workflow added to their account. From here, you can either @CortexTechnicalSupport or add a :ticket: reaction to a question in Slack, and the team will respond directly.
Don’t have a Slack channel? Talk with your Customer Success Manager.
Using CQL reports
CQL reports are ideal when you need to extract, analyze, or share detailed data that goes beyond pass/fail checks, and when you want to create reusable, auto-refreshing reports for ongoing visibility. They allow you to query and visualize raw data from your entities via CQL with more flexibility than what Scorecards or Query Builder provide:
View any expression result, such as the exact number of incidents, deployment counts, or custom data values for each entity
Scorecards and Query Builder require expressions to evaluate to a boolean.
that aggregate and display data from entity metadata, integrations and custom data
by surfacing the underlying data that drives rule outcomes
Export filtered data for further analysis or sharing
Create a CQL report
You will need the Run query builder permission. If you are running queries on third-party integrations, you will also need the Run query builder with third-party integrations permission.
In the main nav of Cortex, click Tools > CQL reports. In the upper right corner of the page, click Create CQL report.
Choose whether to start from scratch or use a template.
If you opt to work from a template, you’ll be able to select from any of your organization’s available templates — along with templates built into Cortex — making it easier to ensure all best practices are being followed.
Note that if the return value is too large (like a 5 MB JSON file) the cell in the report results will error out, so we recommend defining raw values for outputs. The maximum data size that can be the value of a cell is 2048 bytes.
View CQL reports
You can view previously created CQL reports at Tools > CQL reports. Click into a report name to view its results.
Sort and filter CQL reports
You can sort by each column of the report, select which columns are displayed, and filter by AWS account, AWS region, domain, entity, entity type, group, owner, or team.
By default the report displays all entities. Click the Mine tab to view information for only your owned entities.
Share CQL reports
You may need to share a CQL report with teams or leaders to provide detailed, custom insights into entity data, compliance, or operational metrics. Click Export CSV in the upper right corner of the report to generate a CSV file.
A report must be set to Public in order to share it.
Refresh a CQL report
Cortex does not automatically refresh a CQL report. If you did not configure auto refresh for the report, you can refresh it manually: While viewing the results page, click the 3 dots icon, then click Refresh CQL report.
If a report contains expressions written using an outdated version of CQL, you will see a warning banner at the top of the page stating that the report cannot be refreshed. After you update any outdated CQL queries, you will be able to refresh the report.
Enable auto refresh for CQL reports
While , you can schedule an auto refresh. By default, auto refresh is disabled.
If you didn't add auto refresh when creating the CQL report, you can also edit the report later on to enable the setting.
With auto refresh enabled, in the upper right corner of a CQL report page, you will see the last refresh time and the next scheduled evaluation:
Edit a CQL report
To edit an existing CQL report:
Navigate to Tools > CQL Reports. Click the CQL report you want to edit.
In the upper right corner of the CQL report, click Edit.
Make any necessary changes, then at the bottom of the page, click Save.
Using CQL reports to debug Scorecards
You can use CQL reports to help interpret unexpected results from Scorecards.
For example, let's say you have a service that is failing the rule Readme created. However, you believe the service does have a readme file, and you aren't sure why it's failing this rule.
We could create a CQL report from scratch and add a new column for the README CQL expression to check for README.md in the git repo:
After saving the CQL report, you can view the results to see the contents of readme files for each entity. In this report, you will be able to see if the readme contains an error such as "The result is too large to store," which would explain why the entity is failing that rule in the Scorecard.
Semgrep
Semgrep is static application security testing (SAST) tool that includes software composition analysis (SCA). It detects security vulnerabilities in your code and analyzes your open-source dependencies for vulnerabilities. You can use it to scan local repositories or integrate it into your CI/CD pipeline.
Create Scorecards that track progress and drive alignment on projects involving Semgrep security data, allowing you to address and remediate vulnerabilities more efficiently
How to configure Semgrep with Cortex
Prerequisites
Before getting started:
Create an with and permissions.
Configure the integration in Cortex
In Cortex, navigate to the :
Click Integrations from the main nav. Search for and select Semgrep.
Click Add configuration.
After saving your configuration, you are redirected to the Semgrep integration settings page in Cortex. In the upper right corner of the page, click Test configuration to ensure Semgrep was configured properly.
How to connect Cortex entities to Semgrep
Match entity names to Semgrep projects
By default, Cortex will use the (e.g. my-service) as the "best guess" for Semgrep projects. For example, if your entity name is "My Service" or your tag is my-service, then the corresponding project name in Semgrep should also be "My Service" or my-service.
If your Semgrep project names don’t cleanly match the Cortex entity name or tag, you can override this in the Cortex entity descriptor.
Editing the entity descriptor
Under the x-cortex-semgrep block in an , you can define the projects you want based on the Semgrep project ID. For example:
Using the Semgrep integration
Viewing Semgrep information in Cortex
Semgrap vulnerabilities and scans appear on :
in the Code & security block in the entity's overview:\
in the entity's sidebar in Code & security.
This page contains scan results and vulnerability metrics from Semgrep. Click Filter at the top of the vulnerability list to filter by severity.
Scorecards and CQL
With the Semgrep integration, you can create Scorecard rules and write CQL queries based on Semgrep projects.
See more examples in the in Cortex.
Check if Semgrep project is set
Check if entity has a registered Semgrep project in its entity descriptor.
Definition:semgrep (==/!=) null: Boolean
Example
An initial level in a security Scorecard might include a rule to make sure entities are associated with a Semgrep project:
Setting a
List vulnerabilities
List of Semgrep vulnerabilities by severity or type.
Definition:semgrep.vulnerabilities()
Example
You can write a rule to verify an entity has fewer than 10 vulnerabilities:
Get scan results for an entity
Get Semgrep scan results for an entity.
Definition: semgrep.scans()
You could write a Scorecard rule to ensure an entity has fewer than 10 scans:
You could write a rule to ensure an entity has had fewer than 10 new scans in the last week:
View integration logs
This feature is available to Cortex cloud customers.
On the integration settings page, click the Logs tab to view logs from the last 7 days. Learn more in .
Still need help?
The following options are available to get assistance from the Cortex Customer Engineering team:
Email: , or open a support ticket in the in app Resource Center
Slack: Users with a connected Slack channel will have a workflow added to their account. From here, you can either @CortexTechnicalSupport or add a :ticket: reaction to a question in Slack, and the team will respond directly.
Don’t have a Slack channel? Talk with your Customer Success Manager.
Managing Entities
An entity is an object that represents a software construct. A defined collection of entities is known as a . All entities are represented in YAML, can pull in data from integrations, and can be .
Each entity has its own page that centralizes data related to it, allowing you to quickly access the information you're looking for. Learn more in the documentation.
Want to learn more? Check out the Cortex Academy course on , available to all Cortex customers and POVs.
Defining relationship types
The ability to add relationship types is in public beta. Please reach out to Cortex Customer Engineering with any feedback.
Relationship types allow you to define, manage, and visualize relationships between entities within your Cortex workspace, ensuring your organization's structures and dependencies are accurately represented.
Entity details page
Each entity has its own page that centralizes data related to the entity, allowing developers to reduce context switching.
While viewing entities in a catalog, or from the Catalogs > All entities page, click an entity name to open that entity's details page and see an overview of important information:
If there are any active incidents, you will see them at the top of the page.
In the sidebar, you want to see. Pin key information for easier visibility and access. You can include data for on-call, owners, Slack or Microsoft Teams channels, groups, repository, entity relationships, docs links, project management, custom data, and code quality.
Managing Catalogs
A catalog is a defined selection of . You can use catalogs to track and store information about all of the components that make up your infrastructure. This includes everything from services and domains to AWS S3 buckets and RDS, Google Cloud resources, or Azure Resources.
While entities are , catalogs themselves are not defined by a YAML file and must be created in the Cortex UI. Think of catalogs as a folder containing a collection of entities, with each entity defined by its own YAML file. An entity can belong to multiple catalogs, so you can also think of a catalog as a filter that defines which entity types to group together.
In the example screen shot below, the Services page contains a list of all entities that belong to the Service catalog:
incident.io
is an incident management and alerting platform.
Integrating incident.io with Cortex allows you to:
directly from Cortex
View incident data on entity pages in Cortex
Rootly
is an on-call and incident response platform.
Integrating Rootly with Cortex allows you to:
directly from Cortex
on entity pages in Cortex
ServiceNow
is a CMDB (configuration management database) to define, manage, automate and structure IT services. Cortex integrates with ServiceNow to provide engineers with better developer experience while adhering to governance standards. The integration syncs data between systems so both stay current.
Integrating your ServiceNow instance with Cortex allows you to:
from ServiceNow and track ownership of entities
from ServiceNow
Wiz
is a security platform that allows teams to find and fix issues in their code. Cortex integrates with Wiz to bring cloud and container vulnerabilities into your catalog.
Integrating Wiz with Cortex allows you to:
, eliminating the overhead of manually maintaining project-to-entity relationships
in Cortex
Prometheus
Overview
is an open-source monitoring and analytics platform that allows customers to analyze, visualize, automate, and alert on metrics data.
Integrating Cortex with Prometheus allows you to:
Scorecard examples
The Scorecard use cases and examples this is section are based on engineering teams across a wide spectrum of sizes and maturity levels. Learn and what look like.
See additional detailed examples in the :
openapi: 3.0.1
info:
title: My Service
description: This is my cool service.
x-cortex-tag: my-service
x-cortex-type: service
openapi: 3.0.1
info:
title: Chat Service
description: Chat service is responsible for handling chat feature.
x-cortex-tag: chat-service
x-cortex-type: service
x-cortex-parents: # parents can be of type domain only
- tag: notifications-domain
- tag: support-domain
x-cortex-groups:
- python
x-cortex-owners:
- type: group
name: Delta
provider: OKTA
description: Delta Team
x-cortex-slack:
channels:
- name: delta-team
notificationsEnabled: true
description: This is a description for the delta-team Slack channel # optional
x-cortex-link:
- name: Chat ServiceAPI Spec
type: OPENAPI
url: ./docs/chat-service-openapi-spec.yaml
x-cortex-custom-metadata:
core-service: true
x-cortex-dependency:
- tag: authentication-service
- tag: chat-database
x-cortex-git:
github:
repository: org/chat-service
x-cortex-oncall:
pagerduty:
id: ASDF1234
type: SCHEDULE
x-cortex-apm:
datadog:
monitors:
- 12345
x-cortex-issues:
jira:
projects:
- CS
x-cortex-static-analysis:
veracode:
applicationNames:
- My Application
- Second Application
sandboxes:
- applicationName: My Application
sandboxName: My Sandbox
- applicationName: Second Application
sandboxName: Second Sandbox
git.commits().length == 2 AND azureDevops.workItems().length > 4
Username and Password: Enter your xMatters username and password.
Organization slug: Enter the organization slug for your xMatters instance.
This can be found in the URL for your instance (e.g., https://.xmatters.com)
Click Save.
Summary: Enter a title for the incident.
Description: Enter a description of the incident.
Severity: Select a severity level.
At the bottom of the modal, click Trigger incident.
A confirmation screen will appear. In the confirmation, click the link to view the incident in xMatters.
While making sure an on-call policy set is a rule that would be defined in a Scorecard's first level, a rule focused on escalation tiers would make more sense in a higher level.
Ensure that the service principal for the subscription ID has a Reader role.
Configure the Azure Resources integration form:
Account alias: Enter your Azure account alias. Account aliases are used to tie service registrations to different configuration accounts.
Azure tenant ID: Enter your Azure tenant ID.
Client ID and Client secret: Enter your Azure client ID and secret.
Subscription ID: Enter your Azure subscription ID.
Click Save.
You will be redirected to the Azure Resources Settings page in Cortex, where you can optionally choose to include only specified Azure resource types for this integration. You can also enable automatic import for any discovered entities of known types.
.
tag. You can also customize the tag key name on the Settings page.
Make sure an entity has a health check:
Make sure an entity has a tag with a certain key and value:
Organizational slug: Enter the slug for your Buildkite organization.
This can be found in your organization's Buildkite settings, or at the end of your Buildkite URL after navigating to Pipelines.
Click Save.
State
Commit
Created at
ID
Message
Number
Pipeline
State
Pipeline criteria:
Description
Git repository
ID
Name
Slug
Tags
States include CANCELED, PASSED, and FAILED.
Definition: buildkite.builds()
Example
If you're building a Scorecard with an emphasis on operational maturity, you could set a rule to make sure not only that entities belong to a pipeline, but that the pipeline is functioning as expected.
API key: Enter the API key you created in FireHydrant.
Click Save.
Identified
Investigating
Mitigated
Postmortem completed
Postmortem started
Resolved
Started
Summary: Enter a title for the incident.
Description: Enter a description of the incident.
Severity: Select a severity level.
Condition: Nature of the incident - Unavailable, Partially Unavailable, Degraded, Bug, or Operational.
At the bottom of the modal, click Trigger incident.
A confirmation screen will appear. In the confirmation, click the link to view the incident in FireHydrant.
This is also a good way to make sure over time that FireHydrant is set up properly and reporting frequently.
Impact condition name
Name
Severity
Status
Definition:firehydrant.incidents()
Examples
For a Scorecard focused on service maturity or quality, you can use this expression to make sure there are no detected or identified FireHydrant incidents with a severity rating of 1 for a given entity:
You can also tier severity-based rules to indicate progress over time. While the above rule might make sense in the first or second level, a higher-severity rule might make sense in a higher level:
x-cortex-oncall:
xmatters:
id: engineering_group
type: SERVICE
oncall != null
oncall.numOfEscalations() >= 2
oncall.details().id.matches("Sample*") == true
x-cortex-azure:
ids:
- id: /subscriptions/1fbb2da1-2ce7-45e4-b85f-676ab8e685b9/resourceGroups/GROUP1/providers/Microsoft.Compute/disks/vm1_disk1_3d9f85717666435e9e87e4883d31a7e9
alias: my-default-alias # alias is optional and only relevant if you have opted into multi account support
- id: /subscriptions/1fbb2da1-2ce8-45e4-b85f-676ab8e685b0/resourceGroups/GROUP2/providers/Microsoft.Compute/disks/vm1_disk1_3d9f85717666435e9e87e4883d31a7e0
alias: my-other-alias # alias is optional and only relevant if you have opted into multi account support
On the following page, after the integration sync is complete, a list of entities from the integration are displayed. Check the boxes next to any entities you want to import.
If you have a large volume of entites, click Filter in the upper right corner of the results list to select and apply entity type filters.
At the bottom of the page, click Next step.
Edit the details for the entity:
Type: Select Domain.
Entity name: Enter a human readable name.
Identifier: This field is auto-populated based on your entity name. It is a unique identifier for your entity. This is also known as the x-cortex-tag.
Description: Enter a description of the entity to help others understand its purpose.
Groups: Optionally select your entity.
Owners: Define ownership for your entity. We recommend selecting team owners to keep your ownership information up-to-date through any future personnel changes. You may see owners that Cortex . You can accept or reject the recommendations.
When adding an owner, you can also configure one of the following inheritance options:
Append: Select this option to add your entity as an additional owner to all of its child entities.
Parents and Children: Define parent and children domains. This is where you configure the hierarchy for your domain. These can be visualized in the .
On-call: Configure on-call information.
Repository: Select the repository associated with this entity.
When you are finished, click Confirm import at the bottom of the page.
If you selected more than one entity: After the first entity is configured, click the name of the next entity on the right to navigate to the detail editor for that entity.
Click Confirm import.
Manually creating domains
In the main nav of Cortex, click Catalogs > Domains.
At the top of the Domains page, click +Import entities.
Choose Create entities manually.
Configure the form:
Type: Select Domain.
Entity name: Enter a human readable name.
When you are finished, click Confirm import at the bottom of the page.
The hierarchy of entities in Cortex is based on that hierarchy being defined in the entity's YAML file; Cortex does not set hierarchies based on a YAML file's location in your repository.
Domain entity descriptor
If your entity is a domain, you must specify x-cortex-type as domain:
Domain hierarchies
These can be defined in two ways:
From the parent entity YAML
Define children entities using the x-cortex-children tag in the parent entity YAML.
From the child entity YAML
Define parent entities using the x-cortex-parents tag in the child entity YAML.
While defining these relationships top-down (on the parent entity) or bottom-up (on the child entity) will both result in a hierarchy, you may choose one or the other depending on your workflow. For example, if you are frequently making changes to a group of children domains, it may be more efficient to have the children defined on the parent YAML.
Domain children
Define a list of other entities as children for a domain, allowing you to represent a hierarchy of how your entities are modeled across your workspace using the x-cortex-children tag.
Domain parents
Define another entity as the parent for a domain, allowing you to represent a hierachy of how your entities are modeled across your workspace using the x-cortex-parents tag.
Note: Parents must be of type domain.
Ownership inheritance
A common use case for domains is defining ownership for the subtree of entities. Instead of defining ownership individually for every entity in your catalog, you can define ownership at the domain level and have that pass down to all of its children.
The inheritance type for each owner can be one of APPEND, FALLBACK, or NONE. If not set, inheritance is defaulted to NONE.
APPEND: This owner is appended to the list of owners for all child entities.
FALLBACK: In the case where a child has no valid owners, including fallbacks, this fallback will be assigned as the owner. Note that this only applies to a child entity down the hierarchy; it is not the fallback for the parent domain itself.
NONE
Example cortex.yaml
Note: the YAML definition for a domain entity can take file names other than cortex.yaml or cortex.yml; see the .
Creating domains via the API
You can create, update, and delete domains using the .
Note: The only field you cannot edit is the identifier.
This can be done without auth or an explicit Cortex tag in the URL if you do not have access to the Cortex tag or the ability to add authentication headers.
key
Key or title for the custom data. Anything defined before the : will serve as the key.
✓
value
Value for the custom data. Anything defined after the : is the value.
✓
Custom data can be of any type, including scalars (strings, numbers, booleans), objects, and lists.
When you add custom data to an entity's YAML, you'll see the key and value pairs on an entity's Custom data page.
Custom data added via entity descriptor will display with a YAML tag.
Adding descriptions
You can add a description to data by explicitly defining it along with the key and value pairs. While key and value pairs can be defined with any terms when a description is not added, value: must explicitly be defined when a description is included.
Field
Description
Required
key
Key or title for the custom data. Anything defined before the : will serve as the key.
✓
value
Value for the key; should be defined explicitly with value:
✓
Note: While the description field is always optional, it is technically "required" to add a description to custom data.
Adding custom data via the Cortex API
You can pipe custom data directly into Cortex by POSTing to /api/v1/catalog/{tag}/custom-data where {tag}is the x-cortex-tag for a given entity.
The request body requires the following in JSON format:
Field
Type
Description
Required
See the for authentication details.
If a key has already been set through the , an API call will NOT overwrite the existing value. Instead, it will simply return the existing value.
If a key is defined in the entity descriptor, the API cannot override the key. You'll see YAML as the source value in the response body if you encounter this situation.
To explicitly overwrite values set in the YAML file, use the force=true flag as a query parameter.
If you find yourself using the force flag, it may be better to remove the field from the YAML file or update the value in the cortex.yaml file instead to maintain the source of truth.
Custom data added via API will display with a API tag.
Bulk upload entity keys
You can use the bulk upload endpoint to upload multiple keys for one or more entities.
PUT data in the following format to /api/v1/catalog/custom-data:
You can include multiple key and value objects for each tag. The object conforms to the same shape as the single upload API.
In order for an endpoint to populate in this dropdown, it must first be defined as a path in the entity's YAML file. See "Set an endpoint for a dependency" below.
Click Add.
Set an endpoint for a dependency
Before you can select an endpoint from the dropdown when manually defining a dependency, that endpoint must be defined as a path in the entity's YAML file. See the example below:
In the UI, the paths will appear in the Endpoint dropdown:
Define dependencies in the entity descriptor
The x-cortex-dependency field allows you to define a list of outgoing dependencies. A dependency should be directed towards an outgoing service or resource, or more granularly, to a specific endpoint of that entity.
Field
Description
Optional?
tag
The tag of the entity this entity depends on, i.e. the callee. See x-cortex-tag
Define dependencies via the API
See the for authentication details.
YAML is the source of truth. If a dependency has already been set through the cortex.yaml, the API will return an error.
Endpoints are optional. A dependency optionally references an endpoint (method and path) of the callee, and this must already be defined in the callee's cortex.yaml within the paths field. If no endpoint is referenced it is assumed that the caller depends on all endpoints of the callee.
For all requests method or path are optional, however if one is present the other must also be present.
When interacting with an existing dependency, the method and path must be specified correctly to identify it.
Field
Description
Optional?
Create a dependency
POST /api/v1/catalog//dependencies/?method=&path=
Retrieve a dependency
GET /api/v1/catalog//dependencies/?method=&path=
Update a dependency
PUT /api/v1/catalog//dependencies/?method=&path=
PUT replaces entire object. The request body is considered a modified version of the already existing entity. Leaving a field out of the JSON will be interpreted as null.
:::caution PUT replaces entire object The request body is considered a modified version of the already existing entity. Leaving a field out of the JSON will be interpreted as null. :::
To create a new type, enter the type name then click the name in the dropdown.
Learn more about , , and types below.
Name: Enter a name for the link.
URL: Enter the URL.
Description: Add a description of the link.
Click Add.
In the entity descriptor, add a list of link objects:
name, type, and url are required.
The value of type can be defined based on your organization's preferences. Common examples include dashboard, documentation, healthcheck, logs, metrics, and runbook. See the sections below on this page describing OpenAPI, AsyncAPI, and dashboard charts.
embed generated by your dashboard tool.
You must use your tool's embed URL for individual charts.
The URL must be publicly accessible. Or, if you can access the iFrame via VPN, it should be accessible in Cortex while also on the VPN.
Click "Links & docs" on the left side of an entity page.
Our example workspace is named "tfc-guide-example"
Update the instance name in the Terraform variables.tf file.
All Terraform modules come with a file called variables.tf. As part of the Terraform script, we can enter variables for a given set, like region or instance type. In the example screen shot below, the variable name is "My Other Great Instance".
The variable instance name is "My other great instance."
Note: Terraform modules also come with a main.tf file, which contains instructions and information about the action. In our example, the main.tf file describes the instance that we’re going to create through Terraform.
Example of the main.tf file
Terraform stores a “state” about your infrastructure and configuration when it’s deployed. State maps resources to this configuration, and will update any time variables or properties are changed.
After you have added the template to Cortex, you can create a Workflow that includes a Scaffolder block using the template.
Run the Workflow. When you run it, Cortex will automatically open a pull request against the selected repository.
.
Add an HTTP request block. Configure the following fields:
HTTP method: Select POST.
URL: Enter the URL for the Terraform API you want to call.
Headers: Add Authorization: Bearer {{token}} and Content-type: application/(name).
Payload: Build the payload by referencing the outputs of the "User input" block, e.g., {{actions.input.outputs.instance-name}}
Save the Workflow. After saving, click Run at the top of the Workflow to run it.
Integration name: Enter a name for the integration.
Entity tag JQ: Enter the JQ that will be used to extract the entity's Cortex tag from the data. This tells Cortex where in the payload body we can find the Cortex tag.
For example, the payload shown in Step 2 would have .data.codeTag as the JQ, and frontend-service would be the entity's Cortex tag.
If the tag Cortex extracts from the payload does not match an existing Cortex tag, it will result in a 400 error and the custom metadata will not be updated. Learn about .
Key: Enter the custom metadata key.
Data will be stored under the key for entities, similar to adding data via entity descriptor or .
Copy the webhook URL generated in Cortex for this integration.
In GitHub, under Settings > Webhooks, create a webhook.
In the webhook's settings under Payload URL, paste in the webhook URL from Cortex.
Set the Content type to application/json.
Push a commit to your GitHub repository.
In your GitHub settings under Webhooks, click the Recent Deliveries tab to see the payload that will be sent. Because you set the JQ query to .repository.name, the repository name value in the payload will correspond with the Cortex tag in Cortex.
In the example screen shot, the repository name is "michigan":\
Navigate to the entity in Cortex.
In this example, the repository name is "michigan," so we can search in Cortex to find an entity with "michigan" as its Cortex tag.
On the entity's details page, click Custom data & metrics from the entity's sidebar.
Next to the githubTest key, you will see the payload sent from GitHub:\
Domain: Enter your Dynatrace domain necessary to access your environment, depending on whether you use managed, SaaS, or the Environment ActiveGate version.
*API token: Enter the access token you generated in Dynatrace.
Click Save.
In your browser's URL bar, locate the ID in the URL. Copy the ID and store it in a secure location, as you will need this value in the next steps.
The ID is displayed in the URL following sloexp=. For example, https://.apps.dynatrace.com/ui/.../sloexp=&slovis=
On the SLOs page, expand the details for each SLO to display the SLO ID in the URL.
Open your Cortex home page, then navigate to the service you are configuring.
In the upper right corner of the service page, click Switch to YAML.
Paste in the following text, making sure to replace slo-id-1 and slo-id-2 with the SLO IDs you obtained from the Dynatrace URL in the previous steps:
Name
Operation
Remaining budget
SLI value
Datum
Timeseries
SLO target
Source
Thresholds
Name
Threshold
Definition:slos()
Examples
For a Scorecard focused on operational maturity, this expression can be used to make sure an entity has associated SLOs in Dynatrace:
This rule checks that there is at least one SLO is set up. While this rule makes sense in a Scorecard's first level, a rule checking the status of the SLO would make sense in a higher level:
Entities will pass this rule if all SLOs associated with it have "passing" status.
If you're using a self-hosted instance of Mend, you'll need to verify that your Cortex instance is able to reach the Mend instance.
We route our requests through a static IP address. Reach out to support at [email protected] to receive details about our static IP. If you're unable to directly allowlist our static IP, you can route requests through a secondary proxy in your network that has this IP allowlisted and have that proxy route traffic to your Mend instance.
You can find it in the URL for your instance, e.g., https://app.{REALM}.signalfx.com/#/metrics.
Access token: Enter the access token you generated in Splunk.
Click Save.
Target number for the SLO
✓
lookback
(P[n]Y[n]M[n]DT[n]H[n]M[n]S)
✓
operation
>, <, =, =
✓
query
Elasticsearch query for your metric: Use sf_metric to filter by the given metric and add additional dimensions to narrow the searchQueries resulting in multiple datasets will be rolled up according to rollup
Description: Enter a description for the report. This helps others in your workspace understand the purpose of the report.
Enable auto refresh: Enable this toggle setting if this report should be automatically evaluated on a specified interval.
Evaluation window: Set how often you want this report to be evaluated. The minimum refresh window is 12 hours, and the maximum is 336 hours (2 weeks).\
Apply to specific entities: Optionally narrow the scope of your report by selecting specific entities. If left blank, the report will apply to all entities.
Advanced options: You can further refine your selection by including or excluding groups. While adding a CQL expression, you can .
Note that you cannot query third-party integrations when refining the entity selection for a CQL report.
Columns:
Click Add column to start adding new CQL expressions to the report.
If you used a template, you can click the pencil icon next to an existing rule to edit it.
When you are done adding columns, click Create at the bottom of the page.
If you want your report to be publicly available to other users in your workspace, enable the toggle next to Public.
In the video below, see an overview of how Cortex helps you build and catalog your engineering operations assets helping to improve visibility, adoption, and productivity:
By default, Cortex supports the following entity types:
Services: The default type and the core of your catalog, used for entities such as microservices, libraries, components, etc – essentially any codebase-like module. Learn more in Add services.
Domains: An entity that allows you to group your services, resources, and other domains into hierarchical, logical units. Learn more in Add domains.
Teams: An entity to store all of your team data. Learn more in Add teams.
Cortex also supports pulling in resources directly from AWS, Azure Resources, and Google Cloud as their corresponding types.
For AWS, you can select which entity types to include in your .
For Azure Resources, you can select which entity types to include in your .
For Google, see the list of
Custom entity types
In addition, you can create custom entity types to fit your organization's needs. Learn more in Add custom entity types.
Whether you use the UI or GitOps to manage entities, every entity in your Cortex catalogs is defined by a YAML file called the Cortex entity descriptor, also referred to as an entity's Cortex YAML (stemming from cortex.yaml, the name of the file that powers the GitOps approach.)
Any additional metadata you add to your descriptor belongs in the info section of the YAML file. Throughout the Cortex docs, you'll see snippets that start with x-cortex-* – make sure to add this to the info section.
By default, your account is configured to edit entities through the UI. We recommend starting with the UI editor, which includes a built-in YAML editor, then switching over to GitOps when ready for a wider rollout.
If you want to use GitOps to manage your entity YAML files, you can change this setting:
To only allow editing of entities via GitOps, toggle off the setting next to Enable UI editing for new entity types.
To only allow creation of entities via GitOps, toggle off the setting next to Enable UI importing for new entities.
If you want to adjust these settings per entity type, you can disable the toggles for individual entity types. In the list of entity types, disable the toggles next to UI editing and UI importing to use a GitOps approach instead of the UI.
\
When using GitOps, you can define any number of entities in any repository.
Domain definitions should live in the .cortex/domains directory in your repository.
Team definitions should live in the .cortex/teams directory in your repository.
You may store all of your entity definitions in a single repository or you can store the YAML in the repository of the corresponding service.
The Cortex tag (formerly known as the entity tag) - the value of x-cortex-tag in an entity's YAML file - is a customizable unique identifier that's used throughout Cortex. For example, the Cortex tag is used to declare dependencies on other entities or look up information using the Cortex Slack Bot.
The Cortex tag must be globally unique across all entities.
If you attempt to edit an entity’s x-cortex-tag, Cortex will create a new entity with the updated tag while keeping the original entity unchanged. This happens whether you make the change in the UI editor, through the API, or via GitOps. This means both entities will exist until you manually archive or delete the old one.
If you want to re-use an x-cortex-tag value that was previously associated with an entity, the original entity must be deleted before that tag can be used on a new entity.
Cortex ID
A Cortex ID (CID) is a unique, immutable entity ID that can be used outside of Cortex for historical tracking and reporting. It can be used in the API, in CQL queries, in-app, and you can use it with the Cortex Slack Bot. The ID is automatically generated by Cortex and it is 18 characters in length.
In Cortex, the CID for an entity appears in the URL for an entity and at the top of an entity page:
The CID is in the URL and the entity details page.
The CID does not appear in an entity's YAML file, as it cannot be modified.
Adding entities to catalogs
After an entity is imported or created, it will automatically belong to a catalog based on the entity type criteria set for each catalog. When you create a custom catalog, you can set the entity type criteria.
For the default catalogs, the entity type criteria is set by default:
The Services catalog contains service entity types
The Domains catalog contains domain entity types
The Teams catalog contains team entity types
The Infrastructure catalog contains any entities that are not the types service, domain, or team.
Its catalog filter is set to exclude the types service, domain, and team
Managing all entities across catalogs
The All entities page lists all entities that have been imported into Cortex, across all types. This page will open to the Mine tab when a user owns any entities; otherwise, it will default to the All entities tab.
Once you’ve imported entities, you’ll be able to see the entity’s name and tag. In the beginning, you may have just a few dozen entities, but eventually you may have hundreds, if not thousands, of entities across all catalogs.
Search across and filter all entities
There are several ways to search and filter your entities list:
Use the search and filter options in the upper right side of the entities list.
To find specific entities, use the search bar in the upper right corner of the entities list and type to search.
Click Name to select whether you want to sort by name or identifier, and whether to sort ascending or descending.
Click Display to choose whether to show archived entities in the list, and select which columns to display alongside entities. Learn more about the performance indicator columns below.
Click Filter to narrow down your list by associated Git repository, unowned entities, AWS account ID or region, domain, entity type, group, team, or user.
Key performance indicators listed for all entities
Click Display to select whether to display the following key performance indicators as columns alongside entities:
Incidents: Displays how many active incidents are associated with a given entity. This information is pulled from FireHydrant, incident.io, PagerDuty, and Rootly.
Health: When you click into this column in an entity's row, you can view more information on:
Monitors: Shows how entities are performing against monitors you’ve created in your APM. When an entity is passing all monitors, this cell will display All OK; otherwise, it will display Failing, Warning, or No Data, along with how many monitors the entity is not hitting. This information is pulled from Datadog.
Error rate: Shows the percentage of transactions that result in a failure during a pre-specified window. This information is pulled from New Relic.
Apdex (Application Performance Index): Ratio of the number of satisfied and tolerating requests to the total number requests made. This information is pulled from New Relic.
If you have not set up an integration needed to populate a column, that column will display "Not connected." If an integration is established, but the data and/or configuration for an entity do not exist, the cell will display “None.”
View entity types
To view all entity types, go to Catalogs > All Entities then click the Entity types tab.
A Cortex logo appears next to built-in entity types. When you hover over the logo, you will see a "Powered by Cortex" banner:
It's possible to delete entities, but for historical posterity you may want to archive entities. To keep your data up to date without manual effort, we recommend configuring auto-archival of entities when they are no longer detected in your integrations or when their corresponding YAML files are deleted.
It is also possible to manually archive entities in the Cortex UI or via the API. Learn more in Archiving entities.
Understanding and adding entities
To learn more about adding each type of entity, see their documentation pages:
A relationship type defines how two entities relate to either other, and constrains the types of entities that can be the source and destination entities within the relationship.
Cortex provides multiple options for defining a relationship:
Entity relationship: As described on this page, you can customize a relationship type (hierarchical or cyclical) between any entity type.
Team hierarchy: You can define a hierarchical relationship between team entities. Teams can have ownership over other entities. Learn more in Add teams.
Domain hierarchy: You can define a hierarchical relationship between domain entities. You can also configure inheritance; the owner of an entity can be inherited from entities higher in the domain hierarchy. Learn more in Add domains.
Dependencies: You can define a cyclical relationship between non-team entities. Learn more in .
Mapping services to repositories to view the hierarchy of repos and the services they contain. For example, a service is linked to its code repository.
Service
Repository
Cloud account to resource
Associating cloud accounts (like AWS, Google Cloud Project, or Azure subscription) with their respective resources (such as EC2 instances or other cloud resources).
To view all relationship types, go to Catalogs > All entities then click the Relationship types tab.
On the Entities page, click the "Relationship types" tab.
To view the details of a specific relationship type, click its name from the list.
View relationships on entity pages
If an entity belongs to a relationship, you can explore that context directly from its entity details page. Select Relationships in the left sidebar to see all relationship types associated with the entity.
In the example below, the entity California belongs to a relationship called Geography . Relationships default to a Graph view, giving you a visual map of parent/child connections.
From the graph, click any entity to view a quick summary of its metadata. Select Go to entity to navigate directly to that entity's detail page.
Toggle to Table view to see the same data in a structured list. useful for quickly scanning or sorting related entities.
Manage relationship types
Create relationship types and relationship connections
In the upper right corner, click Create > Create new relationship type. \
Configure the details and entity types:
Name: Enter a name for the relationship type.
Identifier: Enter a unique identifier, used to specify this relationship in YAML definitions for this relationship type.
Description: Add a description of the relationship to help others understand its purpose.
Configure the relationship constraints:
Architecture: If you are configuring hierarchical data, such as an org chart, we recommend choosing Acyclical. If you are configuring graph-like data, such as dependencies, we recommend choosing Cyclical.
Definition location: Configure where relationships can be defined — from destination entities, from source entities, or from either.
Configure metadata inheritance.
Enable the Ownership toggle to configure inheritance for the relationship type, then select how metadata will be inherited:
Fallback: This option uses the source's data only if the destination does not have anything defined.
Click Create.
Create relationship connections between entities in the UI
After creating the relationship type, you can configure connections between entities in a relationship. You can do this via the or in the UI, as described below:
Navigate to an . In the upper right corner, click Configure entity.
Click the Relationships link on the left.
At the top of the Relationship Type section, click the dropdown to select which relationship type you are configuring connections for.\
Create relationship connections between entities in the entity descriptor
Relationship types must be or via the API. Once a relationship type exists, you can define the connection in either the source or destination entity's YAML using the x-cortex-relationships tag.
In the example below, a source entity's YAML has a defined relationship type called app-components and has destination entities production-ui and backend-app.
Optionally, this can be configured in the YAML of the destination by replacing source with
Create relationship types via the API
You can create, update, and delete relationship types using the .
Create relationship connections between entities via the API
You can create, update, and delete relationships between entities using the .
You could write a Scorecard rule that ensures an entity has at least one source with the "my-relationship" type:
During an incident, the entity details page allows you to quickly find the information you need all in one place: the active incident itself, who owns the entity and who is on-call, which Slack channel to communicate in, dependencies that could be affected, and the most recent deploys.
If data is not available for a field on the entity page, it will not appear in the overview. For example, if you do not have the Slack integration configured, then the "Slack channels" field will not be displayed.
Configure the entity metadata sidebar
Configure the metadata sidebar
Expand or collapse the metadata sidebar
While viewing an entity details page, click the arrow icon in the lower right corner to expand or collapse the metadata sidebar:
Customize the metadata sidebar
You must be an admin or have the Edit entity types permission to configure the entity sidebar.
While viewing an entity details page:
Expand the metadata sidebar on the right side of an entity details page.
At the bottom of the sidebar, click the two rectangles icon:
Drag and drop metadata categories to reorder them. To remove a category, click the eye icon next to it.
In the left sidebar of an entity, drill further into the entity's recent deploys, events, security vulnerabilities, monitoring metrics, and more, giving you the insight you need to solve an incident quickly and efficiently.
In the sidebar, click into each category for more information:
Entity overview categories
Relationships: See how an entity connects to the rest of your catalog including domain hierarchy, team hierarchy, dependencies, and any custom relationship types you've defined.
Events: A list of recent events sourced from , , , , , , , , , and .
Links & docs: you have added to the entity, along with documentation pulled from the related repository.
Owners: See the teams who own the entity, the related Slack or Microsoft Teams channels, and a list of team members.
Learn more about how to define entity owners in .
Entity YAML: View the that defines this entity.
If you have for this entity and you have the View GitOps logs permission, this page will display the source of the YAML file and a preview of the latest GitOps log.
Cortex features for this entity
Scorecards: A list of any Scorecards that are in progress where this entity is being scored. In additional, see the average score, median score, and a graph showing the entity's scores over time.
Above the Scorecard section, you can choose which scores to include in calculations if the entity is in a hierarchy:
Domains: Click "This entity only" to view only the scores that apply to the domain you are viewing. Select "Include entity's children" to include both the parent domain and its child entities in the score calculations.
Entities with a custom relationship type: Click "This entity only" to view only the scores that apply to the entity you are viewing. Click "[Relationship type] only" to include both the parent and its child entities in the score calculations.
Teams: Click "This entity only" to view the scores that apply only to the team you are viewing. Click "Include entity's children" to include scores for the team, the team's children, entities owned by the team, and entities owned by the team's children.
Initiatives: A list of all active for this entity, including the Scorecard's current level and the due date of the Initiative.
Workflows: A list of that include this entity. If any Workflows are pending approval and you were designated as an approver when the Workflow was created, you will see the pending approval at the top of this page. This page also includes a list of recently run Workflows and the ability to run any related Workflows.
Connections for this entity
Under the "Connections" header, integration data for the entity is contextually grouped. When you configure integrations, data will be pulled in to the following sections on the entity details page:
In the video below, see an overview of how Cortex helps you build and catalog your engineering operations assets helping to improve visibility, adoption, and productivity:
Default catalogs
By default, Cortex comes with four built-in catalogs:
Infrastructure contains all entities representing your infrastructure assets.
Cortex pulls in resources directly from AWS, Azure Resources, or Google Cloud, as their corresponding types out of the box. These resources are automatically added to the Infrastructure catalog.
Domains contains all and their children entities (regardless of entity type), and displays them in a hierarchical view.
Teams contains all and displays them in a hierarchical view alongside a leaderboard based on Scorecards.
You can choose to rename these catalogs to fit your own taxonomy, but note that the custom names of these default catalogs will not override the references to their default names throughout the app. Instead, you could choose to create additional custom catalogs.
Custom catalogs
To customize your Cortex instance to your organization's needs, you can also define custom catalogs in Cortex to represent your infrastructure. See Create custom catalogs below.
Catalog types
There are two types of catalogs:
Entity type catalogs
Define entity inclusion criteria through filters for entity type, tags, or groups.
For example, the built-in "service" catalog is configured to include entities of type service.
Relationship type catalogs
This type enables grouping of entities based on a specific . These catalogs support visualizing hierarchical relationships. They support the ability to have different entity types relate to one another.
For example, the built-in "domain" catalog includes entities associated with each other via parent/child domain relationship. This catalog displays all entities that are a part of the domain hierarchy, including entity types that are not domains.
View catalogs
Click Catalogs from the main nav to view your list of catalogs. You must have the View catalogs permission.
Click "Catalogs" in the main nav to view catalogs.
View a catalog's entity list
When you click into a catalog, you can view all of the entities that belong to that catalog:
Display options for entity relationship catalogs
If a catalog can be configured with a hierarchy (such as domains, teams, or custom catalogs based on relationship types), you can choose what is displayed in the list view:
At the top of the list, click Display.
Configure the display options:
To include the hierarchy in the list view, enable the toggle next to Display hierarchy.
To include entities that are not connected to any other entities, enable the toggle next to Show empty.
To include archived entities in the list view, enable the toggle next to Show archived.
Click Done.
The "All entities" page
All entities
The "All entities" page includes entities across all catalogs and entities of all types, whether the entity is one of the default types or whether it is a custom entity type. To access this page, go to Catalogs > All Entities.
All entity types
To view all entity types, go to Catalogs > All Entities then click the Entity types tab.
On the All catalogs page, you’ll find all pre-defined and custom catalogs in Cortex.
This page will reflect the same list of catalogs you find in the Catalogs dropdown menu in the main nav.
The "All catalogs" page displays all catalogs in the workspace.
Just like "All entities", "All catalogs" includes a search bar and a sort function, as well as a toggle for displaying or hiding Drafts.
From this page, you can create new catalogs and edit existing ones.
Create custom catalogs
You can create catalogs in the Cortex UI. For each catalog, you set the criteria that determines which entities belong to that catalog. In addition, you can define custom entity types to categorize the entities that live in your catalogs.
Because catalogs are not defined by a YAML file, it is not possible to create them via a GitOps workflow.
To create, edit, and delete catalogs, you must have the Edit catalogs permission.
To create a new catalog:
At the top of the "All catalogs" page, click Create catalog.
Configure the "Create catalog" form:
Name: Enter a name for the catalog.
Description: Optionally, enter a description of the catalog.
Display icon: an icon to appear alongside the catalog throughout the app.
URL: Enter a unique URL slug.
By default, the URL slug will be generated based on the catalog’s name, but you can use the URL field to create a custom slug.
Catalog filter: In this section, you can define the entities that are included in your catalog. All entities that match the criteria defined in this section will be automatically included in the catalog. You can use one filter to define a catalog page — choose an entity type or a relationship type.
Option 1: Entity Type: Catalogs can include a combination of any entity types, or can include just one type.
Choose whether to include or exclude the entity types you select.
Save as draft: Choose whether to save the catalog as a draft or publish it. Only admins and managers have the ability to view drafts.
Click Create.
Once the catalog is created, you’ll find it under Catalogs > All catalogs, automatically populated with all entities that apply based on the entity types you've created. Catalogs with a relationship type filter can be displayed as a hierarchy.
Edit catalogs
You can edit a catalog's name, description, URL, display icon, and catalog filter type.
To edit a catalog:
In Cortex, go to Catalogs > All catalogs. Click into the catalog you want to edit, then click Edit catalog at the top of the page.
This will bring you back to the catalog creation page, with all the details from your last save.
Make any changes necessary to the catalog.
At the bottom of the page, click Save catalog.
Track catalog changes
You can use the audit log to track changes made to any of your catalogs. Catalog updates will be listed as CATALOG in the Type column, and the updated catalog will be listed under the Entity column.
The Action column will indicate whether a catalog was created, deleted, or updated.
Adding entities to catalogs
After an entity is imported or created, it will automatically belong to a catalog based on the entity type criteria set for each catalog. When you create a custom catalog, you can set the entity type criteria.
For the default catalogs, the entity type criteria is set by default:
The Services catalog contains service entity types
The Domains catalog contains domain entity types
The Teams catalog contains team entity types
The Infrastructure catalog contains any entities that are not the types service, domain, or team.
By default, any you create will belong to the Infrastructure catalog. If you do not want the entity type to belong to this catalog, you can add the entity type to a different catalog.
Configure catalog display
You must have the Configure appearance settings permission to configure the catalog display.
By default, catalogs will appear in alphabetical order, but you can manually adjust the order that the catalogs appear in the main nav.
Click Integrations from the main nav. Search for and select incident.io.
Click Add configuration.
Configure the incident.io integration form:
Account alias: Enter the alias for your configuration.
API key: Enter your incident.io API key.
Click Save.
Configure the integration for multiple incident.io accounts
The incident.io integration has multi-account support. You can add a configuration for each additional instance by repeating the process above.
Each configuration requires an alias, which Cortex uses to correlate the designated instance with registrations for various entities. Registrations can also use a default configuration without a listed alias. You can edit aliases and default configurations from the incident.io page in your Cortex settings. Select the edit icon next to a given configuration and toggle Set as default on. If you only have one configuration, it will automatically be set as the default.
How to connect Cortex entities to incident.io
Discovery
By default, Cortex will try to "best-guess" the corresponding custom field value in incident.io for all catalog-based custom fields.
Cortex first looks up a custom field values using the name (e.g. My Entity), then the entity identifier (e.g. my-entity). For example, if your entity name is "My Entity," then the corresponding custom tag field in incident.io should either be "My Entity" or "my-entity."
Editing the entity descriptor
Field
Description
Required
name
Name for the entity (from customFieldName)
✓
value
Display name for the entity in Cortex
✓
Field
Description
Required
id
ID for the entity (from customFieldID)
✓
value
Tag for the entity in Cortex
✓
Using the incident.io integration
View incident.io information on entity pages
Once the integration is set up, incident data will appear on entity details pages.
Active incidents detected in incident.io will appear on an entity's details page in the Operations block under the Overview tab. More detailed information is also available under the Operations tab.
Incident data will also be pulled into the incident.io page under the On-call & incidents page in the entity's sidebar.
Trigger an incident
While viewing an entity in Cortex, you can trigger an incident in incident.io:
In Cortex, navigate to an entity. On the left side of an entity details page, click On-call & incidents.
In the upper right side of the entity's "On-call" page, click Trigger incident.
Configure the incident modal:
Summary: Enter a title for the incident.
Description: Enter a description of the incident.
Severity: Select a severity level.
At the bottom of the modal, click Trigger incident.
A confirmation screen will appear. In the confirmation, click the link to view the incident in incident.io.
Scorecards and CQL
With the incident.io integration, you can create Scorecard rules and write CQL queries based on incident.io incidents.
The following options are available to get assistance from the Cortex Customer Engineering team:
Email: [email protected], or open a support ticket in the in app Resource Center
Slack: Users with a connected Slack channel will have a workflow added to their account. From here, you can either @CortexTechnicalSupport or add a :ticket: reaction to a question in Slack, and the team will respond directly.
Don’t have a Slack channel? Talk with your Customer Success Manager.
When active incidents are detected in Rootly, Cortex will display incident information on an entity's details page in the Overview and Operations tabs.
Create Scorecards that track progress and drive alignment on projects involving incidents
Click Integrations from the main nav. Search for and select Rootly.
Click Add configuration.
Configure the Rootly integration form:
Account alias: Enter the alias for your configuration.
API token: Enter your Rootly API token.
Click Save.
Once you save your configuration, you'll see it listed on the integration's settings page in Cortex. If you’ve set everything up correctly, you’ll see the option to Remove Integration in Settings.
You can also use the Test all configurations button to confirm that the configuration was successful. If your configuration is valid, you’ll see a banner that says “Configuration is valid. If you see issues, please see documentation or reach out to Cortex support.”
Configure the integration for multiple Rootly accounts
The Rootly integration has multi-account support. You can add a configuration for each additional instance by repeating the process above.
Each configuration requires an alias, which Cortex uses to correlate the designated instance with registrations for various entities. Registrations can also use a default configuration without a listed alias. You can edit aliases and default configurations from the Rootly page in your Cortex settings. Select the edit icon next to a given configuration and toggle Set as default on. If you only have one configuration, it will automatically be set as the default.
By default, Cortex will use the Cortex tag (e.g. my-entity) or entity name as the "best-guess" for a Rootly service. For example, if your Cortex tag is my-entity, then the corresponding service slug in Rootly should also be my-entity.
If your Rootly service name does not match the Cortex tag or name, you can override this in the Cortex entity descriptor.
The following options are available to get assistance from the Cortex Customer Engineering team:
Email: [email protected], or open a support ticket in the in app Resource Center
Slack: Users with a connected Slack channel will have a workflow added to their account. From here, you can either @CortexTechnicalSupport or add a :ticket: reaction to a question in Slack, and the team will respond directly.
Don’t have a Slack channel? Talk with your Customer Success Manager.
Create Scorecards that track progress and drive alignment on projects involving your ServiceNow teams
Some Cortex users link business applications to ServiceNow projects, creating a clear map of ownership and project alignment. This enables visibility into which projects tie to which business apps, helping track migrations, risk programs, and compliance projects.
How to configure ServiceNow with Cortex
Prerequisites
Your ServiceNow user must have the sn_cmdb_user permission enabled.
You must have the Configure Integrationspermission in Cortex.
Click Integrations from the main nav. Search for and select ServiceNow.
Click Add configuration.
Configure the ServiceNow integration form:
Instance name: Enter your instance identifier.
This can be found in your instance URL, e.g., <instance-identifier>.service-now.com.
Click Save.
Stay on this page for the next steps.
Step 2: Configure table mappings
On the ServiceNow integrations settings page, click Add table mapping on the right.
Configure the "Add table mapping" form:
Choose a mapping type: Select whether your data will map to Domains, Services or Teams.
Table name: Enter a descriptive name.
Table filter query: Optionally, enter a table filter query.
ID column name: Enter the column name that contains the ID of the record.
Name column name: Enter the column name that contains the name of the record.
Description column name: Enter the column name that contains the description of the record.
Note: To import teams, you must configure table mappings for the team, its team members, and their relationships.
Click Preview.
From the preview screen, you will be able to view summary counts, warnings, entity tree, and raw table data that was found based on the the configuration details. Once you've confirmed the data looks correct, you can select save.
How to connect Cortex entities to ServiceNow
To import entities from ServiceNow, follow the steps described below.
The following options are available to get assistance from the Cortex Customer Engineering team:
Email: [email protected], or open a support ticket in the in app Resource Center
Slack: Users with a connected Slack channel will have a workflow added to their account. From here, you can either @CortexTechnicalSupport or add a :ticket: reaction to a question in Slack, and the team will respond directly.
Don’t have a Slack channel? Talk with your Customer Success Manager.
Click Integrations from the main nav. Search for and select Wiz.
Click Add configuration.
Configure the Wiz integration form:
Client ID and Client secret: Enter your client ID and client secret from Wiz.
Tenant data center: Enter the data center from Wiz.
Authentication provider: Select your authentication provider. You can confirm the provider in Wiz under
Click Save.
If you see a "No address associated with hostname" error, verify that you have entered the correct authentication provider.
How to connect Cortex entities to Wiz
Match entity names to Wiz projects
By default, Cortex will use the Cortex tag (e.g. my-service) as the "best guess" for Wiz project. For example, if your entity name is "My Service" or your tag is my-service, then the corresponding project name in Wiz should also be My Service or my-service.
If your Wiz project names don’t cleanly match the Cortex entity name or tag, you can override this in the Cortex entity descriptor.
Considerations for mapping Wiz projects to entities
Expand the tile below to see how Cortex customers have modeled their data when mapping Wiz projects to entities.
Wiz project mapping best practices
Domain-level auto-mapping
Some customers organize their Cortex domain structure to match their Wiz projects, enabling auto-mapping across domains based on their name.
For example:
Cortex domain entity name: Engineering project
Entity tag: engineering-project
Wiz project name: Engineering project
Auto-mapping across multiple integrations
Some customers organize multiple integrations to use consistent names and tags across all of them.
For example:
Cortex domain entity name: Engineering project
Entity tag: engineering-project
Wiz project name: Engineering project
Service-level auto-mapping based on repo structure
Some customers use a standardized repository naming convention that makes service-level auto-mapping simple and automated to the Wiz projects.
Define the following block in your Cortex entity descriptor:
Using the Wiz integration
View Wiz information on entity pages
On an entity details page, you'll see Wiz issues, listed by risk level, under the Code and Security header.
In the entity's sidebar, click Code & Security > Wiz to view a list of Wiz issues including their severity, status, basic details, and a link to view the issue directly in Wiz:
Scorecards and CQL
With the Wiz integration, you can create Scorecard rules and write CQL queries based on Wiz projects.
The following options are available to get assistance from the Cortex Customer Engineering team:
Email: [email protected], or open a support ticket in the in app Resource Center
Slack: Users with a connected Slack channel will have a workflow added to their account. From here, you can either @CortexTechnicalSupport or add a :ticket: reaction to a question in Slack, and the team will respond directly.
Don’t have a Slack channel? Talk with your Customer Success Manager.
Create Scorecards that track progress and drive alignment on projects involving Prometheus SLOs
How to configure Prometheus with Cortex
There are two options for integrating Prometheus: the default configuration method and Cortex Axon Relay, a relay broker allows you to securely connect your on-premises Prometheus data.
Click Integrations from the main nav. Search for and select Prometheus.
Click Add integration.
Configure the Prometheus integration form:
Account alias: Enter your account alias.
Username and Password: Enter your Prometheus basic auth credentials.
Click Save.
Configure Prometheus with Cortex Axon Relay
See for instructions. Make sure to follow the Prometheus-specific instructions for the docker-compose.yml file.
Configure the integration for multiple Prometheus accounts
The Prometheus integration has multi-account support. You can add a configuration for each additional by repeating the process above.
Each configuration requires an alias, which Cortex uses to correlate the designated with registrations for various entities. Registrations can also use a default configuration without a listed alias. You can edit aliases and default configurations from the Prometheus page in your Cortex settings. Select the edit icon next to a given configuration and toggle Set as default on. If you only have one configuration, it will automatically be set as the default.
Connecting Cortex entities to Prometheus
Linking SLOs in Cortex
You can create and manage SLOs by listing relevant SLIs through queries.
Field
Description
errorQuery
Query that indicates error events for your metric.
totalQuery
Query that indicates all events to be considered for your metric.
slo
Target number for SLO.
alias
How Cortex calculates Prometheus SLOs
When Cortex gets an SLO from Prometheus, the following query is calculated for it:
This value is calculated and resolved on an hour window, and calculated back for 7 days. Cortex averages the value for each 1-hour window, then averages each of those hourly averages across the lookback period, before displaying it in your Cortex workspace.
The value is updated when the entity page is loaded and when Scorecards are evaluated.
Using the Prometheus integration
View Prometheus data in entity pages
When an SLO is defined in an entity's descriptor, you'll see detailed data about SLOs in the Monitoring page in the sidebar of an entity details page. See the SLO query, target, the current value for each SLO, and the period of time the SLO is being calculated for. For example, if the time listed is "7 days ago," then the SLO is looking at the time range starting 7 days ago to now..
Scorecards and CQL
With the Prometheus integration, you can create Scorecard rules and write CQL queries based on Prometheus SLOs.
SLOs associated with the entity via ID or tags. You can use this data to check whether an entity has SLOs associated with it, and if those SLOs are passing.
Definition:slos: List<SLO>
Examples
In a Scorecard, you can use this expression to make sure an entity is passing its SLOs:
Use this expression to make sure latency Service Level Indicator (SLI) value is above 99.99%:
View integration logs
This feature is available to Cortex cloud customers.
The following options are available to get assistance from the Cortex Customer Engineering team:
Email: [email protected], or open a support ticket in the in app Resource Center
Slack: Users with a connected Slack channel will have a workflow added to their account. From here, you can either @CortexTechnicalSupport or add a :ticket: reaction to a question in Slack, and the team will respond directly.
Don’t have a Slack channel? Talk with your Customer Success Manager.
Learn more about planning and managing migrations using Cortex in the
Setting goals in Scorecards
Start with aspirational goals
Scorecards are often aspirational. For example, an SRE team may define a Production Readiness Scorecard with 20+ criteria that they think their services should meet to be considered "ready" for SRE support.
The engineering team may not be resourced to actually meet those goals, but setting objective targets helps drive organization-wide cultural shifts and sets a baseline for conversations around tech debt, infrastructure investment, and service quality.
You can add as many levels as you want to a Scorecard. You can also add as many rules to each level as makes sense for the Scorecard, but keep in mind that an entity must pass all rules in a given level in order to progress to the next one.
Motivate developers with early wins
When creating rules, we recommend starting with smaller, achievable goals within the Scorecard's first level. Early wins help teams build confidence and momentum. Introducing too many complex rules upfront can feel overwhelming and discouraging.
Focusing on clear, incremental improvements will create a culture of steady progress. Teams will see tangible improvements in reliability, documentation, or readiness without needing a massive investment of time. Once the basic benchmarks are in place and widely adopted, you can expand to more advanced rules, ensuring the process feels supportive and achievable rather than punitive.
Remediate failed rules
Sometimes, an entity or team will fail a rule in a Scorecard. This gives you the opportunity to identify issues and take action on them, leading to incremental improvements over time. Learn more about evaluating Scorecards and remediating failed rules in Review and evaluate Scorecards.
Common Scorecard use cases and example rules
Cortex users commonly define Scorecards across several categories:
Development Maturity: Ensure services and resources conform to basic development best practices, such as established code coverage, checking in lockfiles, READMEs, package versions, and ownership.
Development maturity rules
Development Maturity: Ensure services and resources conform to basic development best practices, such as established code coverage, checking in lockfiles, READMEs, package versions, and ownership.
git.fileExists("package-lock.json")
Developers should be checking in lockfiles to ensure repeatable builds.
sonarqube.metric("coverage") > 80.0
Set a threshold that’s achievable, so there’s an incentive to actually try. This also serves as a secondary check that the service is hooked up to Sonarqube and reporting frequently.
git.lastCommit().freshness = 1
Ensure that a rigorous PR process is in place for the repo, and PRs must be approved by at least one user before merging.
git.fileContents("circleci/config.yml").matches(".*npm test.*")
Enforce that a CI pipeline exists, and that there is a testing step defined in the pipeline.
Operational Readiness: Determine whether services and resources are ready to be deployed to production, checking for runbooks, dashboards, logs, on-call escalation policies, monitoring/alerting, and accountable owners.
Operational readiness rules
ownership.allOwners().length > 2
Incident response requires crystal-clear accountability, so make sure there are owners defined for each service or resource.
oncall.numOfEscalations() > 1
Check that there are at least 2 levels in the escalation policy, so that if the first on-call does not acknowledge, there is an established backup.
links("runbooks").length >= 1
Create a culture of preparation by requiring runbooks to be established for the services or resources.
links("logs").length > 1
When there is an incident, responders should be able to find the right logs easily. Usually, this means load balancer logs and application logs.
embeds().length >= 1
Responders should have standard dashboards readily accessible for every service or resource in order to speed up triage.
custom("pre-prod-enabled") == true
Use an asynchronous process to check whether there is a live pre-production environment for the service or resource, and send a true/false flag to Cortex using the custom metadata API.
sonarqube.metric("vulnerabilities") < 3
Ensure that production services are not deployed with a high number of security vulnerabilities.
Operational Maturity: Monitor whether services are meeting SLOs, on-call metrics look healthy, and post-mortem tickets are closed promptly, gauging if there too many customer-facing incidents.
Operational maturity rules
oncall.analysis().meanSecondsToResolve < 3600
Make sure that issues are resolved in a reasonable amount of time. If they’re not, you can dig into the root cause.
oncall.analysis().offHourInterruptions startOfMonth(-3)")< 2
A reliable service or resource should not be a source of frequent customer-facing incidents.
jira.numOfIssues("labels=compliance") < 3
Make sure there are no outstanding compliance or legal issues affecting the service or resource.
snyk != null
The first step in monitoring security is making sure each service has as associated Snyk project.
git.lastCommit().freshness 0
Making sure each entity has at least one owner helps ensure updates don't fall through the cracks.
git.numOfRequiredApprovals() > 0
Changes should be pushed through unless there is at least one approval.
sonarqube.metric("coverage") > 70
By monitoring code coverage, you can get a sense of how much of your code has been tested — entities with low scores are more likely to be vulnerable to attack.
git.branchProtection() != null
Make sure that your default branch is protected, as vulnerabilities here are critical.
sonarqube.freshness() < duration("P7D")
And check to make sure a SonarQube analysis has been uploaded within the last seven days, so teams are monitoring for compliance to coding rules.
snyk.issues() < 5sonarqube.metric("security_hotspots") < 5sonarqube.metric("vulnerabilities) semver("1.1.3")
Having every CI pipeline send a current version to Cortex on each master build lets you catch services or resources that rely on outdated versions of tooling, like CI or deploy scripts.
package("apache.commons.lang") > semver("1.2")
Cortex automatically parses dependency management files, so you can easily enforce library versions for platform migrations, security audits, and more.
Best Practices: Define organization-wide best practices, such as infrastructure + platform, SRE, and security. For example, the Scorecard might help you ensure the correct platform library version is being used.
Best practices are unique to every organization and every application, so make sure to work across teams to develop a Scorecard measuring your organization's standards.
The following example uses JavaScript best practices:
JavaScript best practices
Best practices are unique to every organization and every application, so make sure to work across teams to develop a Scorecard measuring your organization's standards.
The following example uses JavaScript best practices:
git.fileExists("yarn.lock") or git.fileExists("package-lock.json")
Make sure a Lockfile is checked in to provide consistency in package installs.
git.fileExists(".prettierrc.json") or git.fileExists(".eslintrc.js")
Projcets should have a standard linter.
jq(git.fileContents("package.json"), ".engines.node") != null
Node engine version should be specified in the package.json file.
jq(git.fileContents("package.json"), ".devDependencies | with_entries(select(.key == \"typescript\")) | length") == 0 or git.fileExists("tsconfig.json")
Typescript projects should have a tsconfig checked in.
jq(git.fileContents("package.json"), ".engines.yarn") == null or jq(git.fileContents("package.json"), ".engine.npm") = "please-use-yarn"
If a project is using yarn, it should not allow NPM.
jq(git.fileContents("package.json"), ".engines.yarn") == null or !(semver("1.2.0") ~= semverRange(jq(git.fileContents("package.json"), ".engines.yarn")))
Finally, ensure that the yarn version being used is not deprecated.
Create that include rules related to Sentry errors
How to configure Sentry with Cortex
Prerequisites
Before getting started:
Create a in your Sentry user settings.
The token requires Read for the Issue & Event and Project scopes.
Configure the integration in Cortex
In Cortex, navigate to the :
Click Integrations from the main nav. Search for and select Sentry.
Click Add configuration.
After saving your configuration, you are redirected to the Sentry integration settings page in Cortex. In the upper right corner of the page, click Test configuration to ensure Sentry was configured properly.
How to connect Cortex entities to Sentry projects
Discovery
By default, Cortex will use the (e.g., my-entity) as the best guess for Sentry projects. For example, if your Cortex tag is my-entity, then the corresponding project in Sentry should also be my-entity.
If your Sentry projects don't cleanly match the Cortex tag, you can override this in the Cortex entity descriptor.
Editing the entity descriptor
You can define projects under the x-cortex-sentry block:
Field
Description
Required
Using the Sentry integration
Viewing Sentry errors on an entity
Error data will appear on an . In an entity's sidebar, click Error tracking to view detected issues for each Sentry project. At the top of the page, see a list of Sentry projects associated with an entity. Each project listed in Cortex links back to the .
Under the Issues header on the Error tracking page, you'll find a list of all issues related to the projects that Cortex detected in Sentry. Each issue in the list links back to that . Cortex will pull in the title and tags for each issue.
Events
Sentry issues and events will also appear in an entity's event timeline, found under Events in the sidebar. This allows users to contextualize Sentry issues with other key data - like deploys or errors discovered from other integrations - during incidents or migrations.
Using the Cortex Slack Bot with Sentry
If you have also configured the , you can use the command /cortex sentry <tag> in to get a list of all recent Sentry issues for a given entity. tag is the .
Scorecards and CQL
With the Sentry integration, you can create Scorecard rules and write CQL queries based on Sentry projects.
See more examples in the in Cortex.
Check if Sentry project is set
Check if entity has a registered Sentry project.
Definition:sentry (==/!=) null
Example
For a production readiness Scorecard, you can use this expression to make sure entities are linked to a Sentry project.
This can also serve as a way to confirm that entities are synced with Sentry and reporting frequently.
Number of events
Counts Sentry events for a given to a max of 1,000.
If no query is provided, the rule will count unresolved events by default.
Definition:sentry.numOfIssueEvents((<query>))
Example
Number of issues
Counts Sentry issues for a given custom query to a max of 300.
If no query is provided, the rule will count unresolved issues by default.
Definition:sentry.numOfIssues((<query>))
Example
The maximum number of Sentry events fetched for any query is 1,000, while the maximum number of issues fetched is 300.
View integration logs
This feature is available to Cortex cloud customers.
On the integration settings page, click the Logs tab to view logs from the last 7 days. Learn more in .
Still need help?
The following options are available to get assistance from the Cortex Customer Engineering team:
Email: , or open a support ticket in the in app Resource Center
Slack: Users with a connected Slack channel will have a workflow added to their account. From here, you can either @CortexTechnicalSupport or add a :ticket: reaction to a question in Slack, and the team will respond directly.
Don’t have a Slack channel? Talk with your Customer Success Manager.
Eng Intelligence
Spot problems early and drive action in Cortex
Eng Intelligence provides you with key metrics and high-level data to gain insights into services, bottlenecks in the pull request lifecycle, incident response, and more. These metrics can give context to cross-team activities and indicate areas that need deeper investigation, allowing you to quickly remediate and improve productivity across your teams.
Eng Intelligence features include:
Dashboards:
The gives clear insights into how fast, reliable, and efficient your development practices are.
The visualizes your team's success across the software development lifecycle.
The provides insight into Copilot adoption and engagement across your engineering teams.
allow you to create shared views of the key engineering metrics that matter most to your organization
: Analyze trends over time and drill into the underlying data for investigation. Explore metrics for , , project management (), and incident management ().
: The ability to define your own custom time series metrics to power the analytics in Eng Intelligence, drawing from your integrations with Cortex or your organization's internal data.
Note: After completing the initial integration setup, Eng Intelligence data may take up to 24 hours to fully appear as we backfill up to 6 months of historical data. You may see partial data during this process.
Learn about .
Eng Intelligence overview video
Measuring success with Eng Intelligence in Cortex
In practice, success means that teams are not only tracking metrics like cycle time, deployment frequency, change failure rate, and mean time to recovery (MTTR), but they are also taking action to make progress based on how the metrics are trending. The focus should be less about hitting specific benchmarks and more about creating continuous feedback loops that drive consistent improvement.
Eng Intelligence goals
Eng Intelligence metrics provide clear, actionable insights into how your teams work, allowing you to find opportunities to improve delivery speed, reliability, and quality.
Before setting goals, we recommend establishing a baseline on your top-priority metrics.
Early signs of improvement
Leading indicators show that teams are learning from Eng Intelligence metrics and effectively making changes in their day-to-day work. For example:
Faster feedback loops: Time to first PR review, Time to PR approval, and Work item lead time steadily decrease over a given period.
Smaller, more frequent PRs: PR size trends downward while merged PR count increases.
Balanced workloads: More unique PR authors over time, showing distributed contribution. For project management metrics, a balance of
Outcomes of improvement
Lagging indicators can measure whether your organization is seeing tangible improvements in delivery and reliability. For example:
Cycle time improves from baseline.
Deployment frequency increases without increased failure rates.
MTTR decreases after incidents.
Best practices for reviewing Eng Intelligence metric trends
To make your data more meaningful, we recommend the following best practices:
Segment by teams and services to avoid skewed organization-wide averages.
Look for trends rather than snapshots. Success is measured over time; a short-term fluctuation can be misleading.
When you identify process gaps with Eng Intelligence, take action to drive adoption of standards: Use or to encourage your teams to get their owned services aligned with standards. Use to streamline repeatable tasks for engineers so they can focus on other work.
Defining success
The following are common ways to confirm successful use of Eng Intelligence features:
Leadership uses the dashboards to make strategic decisions (e.g., during planning cycles).
Teams are actively using the dashboards to spot bottlenecks.
Metrics drive measurable changes in process, tooling, and culture.
Accessing Eng Intelligence
Prerequisites to using Eng Intelligence features
Cortex users with the View Eng Intelligence can access Eng Intelligence. Users with the Configure Eng Intelligence permission can configure Eng Intelligence settings.
Before using Eng Intelligence, make sure you have configured your version control providers, PagerDuty, and Jira with the proper permissions. See each integration's documentation page for required permissions and configuration instructions:
To get started, click Eng Intelligence from the main nav in Cortex.
See the docs for more information on each part of Eng Intelligence:
Cortex Query Language (CQL)
Cortex Query Language (CQL) is a proprietary domain-specific language (DSL) you can use to query details in-depth about your Cortex entities. CQL is at the core of many Cortex features, from defining how Scorecards evaluate health and readiness to deciding which entities a plugin should appear on.
With CQL, you can:
Query your data immediately (including from third-party integrations or custom data), without having to move it, transform it, or wait for batch jobs
Cortex does not require you to configure custom processes for each new standard you want to track
You can , allowing you to do arbitrary JSON manipulations (e.g., fetch nested fields, group by, sum over, etc.). Cortex can transition seamlessly between CQL and JQ data types.
Use basic arithmetic and utility functions to get the data you need
Customize rules to query information needed to assess your processes quickly
For example, you can .
Create reusable to view any query result, such as the number of incidents your services had in the last week
CQL allows you to ask multi-source questions, such as, "Who's on call for services in our payment product?" or "Which services are still on the old secrets manager?"
It also provides a consistent way to write rules, regardless of the data source. For example, you can use git.fileExists() to search across all of your Git repositories without needing to specify the Git provider.
CQL basics
See additional CQL instructions and examples in the in your workspace.
CQL format and data sources
CQL queries use the format data sourcefunctionquantifier, with the function and quantifier options differing depending on the data source and type.
The data sources for CQL are:
Entity metadata: Core entity details
Example query: dependencies.in().length
Integrations: Data from
CQL expressions return different data types, and each type supports specific operations within queries. See the available data types and their supported operations in the .
Combining CQL expressions
You can combine CQL expressions in multiple ways:
Use AND to require multiple conditions to be true
Example: entity.type() == "container" AND entity.tag() == "production"
Use OR
Captures
You can include entity or CQL evaluation data in a rule's description and failure message using captures. This will enable you to create a Scorecard rule description or failure message that reflects the rule’s score and affected entity descriptor information (including dependencies and custom data if set in the YAML). Captures allow you to update your rule expressions to “capture” certain pieces of an expression into variables.
Learn more about captures
See additional instructions on using captures in .
Read about a capture use case in .
CQL testing
Anywhere in Cortex where you use CQL, testing functionality allows you to quickly review and iterate on your queries. Below the CQL editor, select up to 10 entities to test against then click Test. Test results appear per entity below the editor.
You can test both boolean and non-boolean expressions anywhere in Cortex, but you can only save non-boolean expressions in .
CQL tools
The Query builder tool
The Query builder allows you to leverage all of CQL's power to investigate information about your entities without building an entire Scorecard.
The functionality of the Query builder depends on your . Users who have the ability to edit Scorecards can run queries that talk to third-party integrations. Users without those permissions can run queries on custom data and anything else that exists within Cortex. Users classified as viewers are not able to run queries.
To see the Query builder, click Tools > Query builder in the main nav.
Using custom data in CQL queries
You can add to any entity, and you can access custom data from any . For example, if you run a security scanning tool that isn't in the list of existing integrations, you may run a vulnerability scan as part of your CI process and then send that data to Cortex.
With the Query builder, you can query against any of this custom data. Anything that can be evaluated with a Scorecard will display in the Query builder, which allows you to essentially use Cortex as a database. Because Cortex is able to pull data from many data sources, the Query builder can even provide more insight than GitHub search.
CQL explorer
contains instructions and examples for specific data types, entity metadata, custom data, and more.
You can access it via Query builder or as a standalone page:
On the Query builder page: On the right side of the Query builder, click the CQL explorer tab to view CQL instructions and examples for specific data types, entity metadata, custom data, and more.\
As a standalone page:
Click the flag icon on the right side of your Cortex workspace.\
CQL reports
CQL reports allow you to query all of the raw data in Cortex and build a custom report on the data. Learn more in .
Running and saving CQL queries
To learn about running queries and saving queries, see .
Integrations
Sync your data to power your Engineering Operations Platform. Cortex supports , , and .
All users can view the integration page to see what is configured and whether your configurations are healthy. Users must have the Configure Integrations permission to install, uninstall, and configure integrations.
Third-party integrations
Internally hosted integrations
Cortex Axon is a framework that can be used to build jobs that run in your environment and securely send data to Cortex. It includes:
Custom handlers: It makes it easy to write code against the Cortex API that can send data to Cortex either on a regular interval, a cron schedule, or after processing a webhook.
See the for more information.
Snyk
is a cybersecurity platform that scans for and surfaces vulnerabilities across your codebase.
Integrating Snyk with Cortex allows you to:
, quickly connecting issues to entities and their owners
Enhance the Snyk experience by aggregating issues into an entity's event timeline so they can be understood in the context of other events, like deploys and on-call incidents
openapi: 3.0.1
info:
title: Payments
description: This is my cool domain.
x-cortex-tag: payments-domain
x-cortex-type: domain
x-cortex-custom-metadata:
regions-of-brain:
value: 3
description: cerebrum, cerebellum, brainstem
brain-hemispheres:
value: 2
description: The brain has a left and a right hemisphere.
info:
x-cortex-dependency:
- tag: braavos
method: GET
path: /2.0/users/
description: ensure user has payment information configured
metadata:
tags:
- billing
- identity
prod: true
openapi: 3.0.1
info:
title: Endpoint Example Service
description: "This is an example"
x-cortex-tag: endpoint-example-service
x-cortex-type: service
paths:
/hello/world:
get:
description: Some description
requestBody:
description: optional
responses:
"200":
description: optional
deprecated: false
/another/path:
put:
deprecated: false
x-cortex-link:
- name: Human Readable Name
type: runbook
url: https://cortex.io
description: Optional Description
x-cortex-link:
- name: My Spec
type: OPENAPI
url: ./docs/my-openapi-spec.yaml
x-cortex-link:
- name: My GitHub Spec
type: OPENAPI
url: github:org/repo:path/to/file
x-cortex-link:
- name: My GitLab Spec
type: OPENAPI
url: gitlab:namespace/project:path/to/file
x-cortex-slos:
prometheus:
- errorQuery: sum(rate(http_server_requests_seconds_count{code=~"(5..|429)"}[5m]))
totalQuery: sum(rate(http_server_requests_seconds_count[5m]))
slo: 99.95
alias: my-prometheus-instance # alias is optional and only relevant if you have opted into multi account support
name: my-slo-name
(1 - ({errorQuery}) / ({totalQuery}))
This can be found in Mend SCA under the Integrate tab.
User key: Enter your Mend user key.
This can be found in Mend under User profile > User keys.
URL type: Select your Mend URL type depending on the server URL for your Mend instance.
Select NEW if the server URL is saas.mend.io.
Select LEGACY if the server URL is saas.whitesourcesoftware.com.
Select CUSTOM if using a dedicated instance.
Custom URL: If using a dedicated instance, enter your Mend server URL.
Alias for the configuration in Cortex (only needed if you have opted into multi-account support)
alias
Alias for the configuration in Cortex (only needed if you have opted into multi-account support)
User Settings > Tenant
.
Jira project name: engineering-project
When you integrate Cortex with Jira, Cortex will tie Jira tickets to entities by searching for any tickets where the label, component, or project field for the work item includes the Cortex tag.
Wiz project name: eng-repo
Host: Enter your self-managed Prometheus hostname.
Tenant ID: Optionally, enter your tenant ID.
If you have multiple tenants, you can enter an ID here to monitor a specific tenant.
Ties the SLO registration to a Prometheus instance listed under Settings → Prometheus. The alias parameter is optional, but if not provided the SLO will use the default configuration under Settings → Prometheus.
name
The SLO's name in Prometheus. The name parameter is optional.
Auth token: Enter the personal token you generated in Sentry.
Organization slug: Enter your Sentry organization slug.
You can find this in your Sentry URL, e.g., https://sentry.io/organizations/{SLUG}/issues/.
Host: If using a self-hosted Sentry instance, enter the URL here without the API path (e.g., bugsnag.getcortexapp.com).
Click Save.
For a Scorecard focused on operational maturity, you can check for any unresolved issues that were first seen within a week.
For a Scorecard focused on operational maturity, you can pull in the number of Sentry issues to make sure entities are functioning as expected.
For a Scorecard focused on code quality, you can write a more focused rule to make sure there haven't been any issues in production environments in the last week.
Fallback: Select this option to add your entity as an owner to child entities if the child entity has no other valid owners.
None: Select this option if you do not want to configure inheritance. The owner will own the domain you are creating, but will not be configured as an appended or a fallback owner.
Identifier: This field is auto-populated based on your entity name. It is a unique identifier for your entity. This is also known as the x-cortex-tag.
Description: Enter a description of the entity to help others understand its purpose.
Owners: Define ownership for your entity. We recommend selecting team owners to keep your ownership information up-to-date through any future personnel changes.
When adding an owner, you can also configure one of the following inheritance options:
Append: Select this option to add your entity as an additional owner to all of its child entities.
Fallback: Select this option to add your entity as an owner to child entities if the child entity has no other valid owners.
None: Select this option if you do not want to configure inheritance. The owner will own the domain you are creating, but will not be configured as an appended or a fallback owner.
Parents and Children: Define parent and children domains. This is where you configure the hierarchy for your domain. These can be visualized in the relationship graph.
On-call: Configure on-call information.
Repository: Select the repository associated with this entity.
: This owner owns the domain, but not necessarily any of its children (no inheritance).
The actual endpoint (as defined in the OpenAPI file) the caller depends on
Required if method is present
description
A description of the dependency.
Yes
metadata
JSON metadata tags for the relationship. Supports arbitrary objects.
Yes
No
method
HTTP method if depending on a specific endpoint
Required if path is present
path
The actual endpoint this dependency refers to
Required if method is present
description
A description of the dependency.
Yes
metadata
JSON metadata tags for the relationship. Supports arbitrary objects.
Yes
callerTag
The tag of the caller.
No
calleeTag
The tag the caller depends on.
No
method
When adding or editing columns, you can write a CQL expression or use the form builder, which allows you to select rules from your configured integrations. To use the form builder, click the Form tab:
When you are done adding a column, click Save column at the bottom of the side panel.
By default, any custom entity types you create will belong to the Infrastructure catalog. If you do not want an entity type to belong to this catalog, you can add the entity type to a different catalog.
Create relationship type catalog: Enable this option to create a catalog for this relationship type.
Source entity types: Search for and select the entity types which will be the source for this relationship. Selecting no entity type means that all entity types are available as sources.
You can also customize the singular and plural wording of the entity types and the cardinality.
Destination entity types: Search for and select the entity types which will be the destination for this relationship. Selecting no entity type means that all entity types are available as destinations.
You can also customize the singular and plural wording of the entity types and the cardinality.
Append: This option appends the source's data to the destination, even if it already has data defined.
After selecting the relationship type, you can search for and select entities in the Sources dropdown and in the Destinations dropdown.
At the bottom of the page, click Save changes.
destination
in the YAML above.
The relationship between entities in Cortex is based on the relationship being defined in the entity's YAML file; Cortex does not set hierarchies or relationships based on a YAML file's location in your repository.
AWS account
GCP
Azure subscription
AWS resources (e.g., EC2)
Google Cloud resources
Azure resources
Service to environment
Linking services to their deployment environments.
Service
Environment
Monorepo
Mapping multiple services to a single repository.
Repository
Service
Service to endpoint
Associating services with their endpoints.
Service
Endpoint
Data center modeling
epresenting data centers and their relationships to other infrastructure components.
Proactive incident management: Change failure rates decrease as deploy insights are integrated.
Higher engineering satisfaction is reported in internal surveys as bottlenecks are resolved.
The backlog of work items created stabilizes or decreases while work items are steadily being completed, indicating the team is successfully matching capacity to demand.
Improvements are sustained and repeatable, not just short-term spikes.
Cortex uses official APIs provided by each tool to pull live data directly from your systems. This means when you're viewing an entity, you're seeing the most current information with no manual syncing or stale data to manage.
Cortex supports integrations across essential use cases for engineering excellence:
You can source data from an internally-hosted system and reflect that data in Cortex. See Internally hosted integrations for more information.
Custom webhook integration
You can use custom data webhooks to create unique URLs that you can use to directly POST arbitrary JSON payloads without authentication headers or a Cortex tag. See Custom webhook integrations for more information.
SSO integrations for Cortex workspace access
Cortex offers the following integrations for SSO access to your Cortex workspace:
Cortex has built a distributed self-throttling system to ensure that certain functionality, such as CQL evaluations or background syncs to pull data from integrations, are not going over the rate limit thresholds for specific vendors. It handles different rate limit thresholds for different APIs within the same integration, which is common for git APIs such as Bitbucket.
The system is designed to proactively throttle before hitting a 429 from the vendor, and it works regardless of how many evaluators are trying to access that integration. Note that this system does not track other requests with the same token or undocumented limits set by vendors.
Troubleshooting with integration logs
This feature is available to Cortex cloud customers.
While viewing an integration's settings page, click the Logs tab to view error logs from the last 7 days. You can filter the logs list by configuration and by operation (for example, you could filter to view errors surfaced only via Scorecards).
Click into a log to get more information, including time stamp, status code, full error, request path, and more, enabling you to troubleshoot integration issues.
This documentation page walks you through configuring internal integrations with Axon Relay.
How it works
Cortex Axon uses an open-source project published by Snyk called Snyk Broker. Snyk Broker uses WebSockets to create a secure tunnel between the internal network and cloud-hosted Cortex. HTTP requests are redirected through this WebSocket channel to the Axon agent. You do not need to open inbound firewall ports, as the tunnel is initiated from the internal network.
When deploying Axon, you provide your API tokens or credentials as secrets stored on infrastructure you own, within your network. Axon securely holds these credentials and uses them to proxy requests to third-party integrations. Your sensitive information stays inside your virtual private cloud (VPC) and is never exposed to Cortex cloud services.
This is what the process looks like:
On the Cortex side, you register the integration, using an alias name you provide.
The Cortex Axon Docker container is started with your Cortex API key, the integration type, and the alias.
The Cortex Axon agent connects to the Cortex service, authenticates, and registers itself with the integration type and alias name.
The agent starts an instance of the snyk-broker client process, and uses configuration details from the /register call (the registration in the previous step) to connect to the Cortex backend instance of the snyk-broker server.
Once this is established, API calls made on the Cortex side are relayed to the internal network, and the responses are relayed back to the Cortex service.
How to use Cortex Axon Relay
Axon is composed of an agent which runs in a Docker container (cortex-axon-agent) and integrates with Kubernetes, creating a secure tunnel between the broker and Cortex.
Click Integrations from the main nav. Search for and select Snyk.
Click Add configuration.
Configure the integration form:
API token: Enter the API token you generated in Snyk.
Region: Enter the Snyk where your data is hosted. The default region is USA.
Click Save.
After saving your configuration, you are redirected to the Snyk integration settings page in Cortex. On this page, you'll see a list of detected organizations pulled from Snyk, along with the unique Snyk ID and internal name associated with each organization.
How to connect Cortex entities to Snyk projects
Discovery
Cortex uses the Git repository as the "best guess" for the corresponding Snyk project since Snyk projects are connected to repositories. Cortex will search for all Snyk projects across all Snyk organizations and pull in projects associated with the same repository. For example, if the GitHub repo associated with your Snyk instance is my-org/repo, then the entities in Cortex should also be associated with my-org/repo.
Editing the entity descriptor
You can define projects under the x-cortex-snyk block:
Field
Description
Required
organization
The organizationID or organizationSlug in Snyk
✓
projectId
The projectID defined in Snyk
✓
You can define organization with the organization ID or its slug in Snyk.
Using the Snyk integration
Viewing Snyk vulnerabilities on an entity
Once the Snyk integration is set up, you'll be able to find information about vulnerabilities for each entity linked to a discovered repo.
Entity page overview
On an entity details page overview, see vulnerabilities listed under the Code & security block. Within this block, issues and vulnerabilities are grouped by severity: Critical, High, Medium, and Low. Click into any of these to open a list of all applicable issues and vulnerabilities.
Entity code & security sidebar
In an entity's sidebar, click Code & security > Snyk to view detected issues and vulnerabilities from Snyk, including the associated organization name and project name.
Because Snyk aggregates problems as "issues," data pulled in from Snyk will be listed as issues, while data pulled in from a Git source will be listed as vulnerabilities.
Vulnerabilities pulled from Git sources display the project name and a severity tag. Each issue pulled from Snyk displays the following information, when available:
Title
Issue ID (linked to the issue in Snyk)
Publish date
Severity tag
Priority score tag
Event timeline
Issues from Snyk and vulnerabilities detected in Git appear in the entity's event timeline, which you can find from the Events link in the entity's sidebar. Issues and vulnerabilities display alongside other events, such as K8s changes, Git commits, and on-call incidents.
Scorecards and CQL
With the Snyk integration, you can create Scorecard rules and write CQL queries based on Snyk projects.
Check if entity has a registered Snyk project in its entity descriptor. If no registration exists, but there is a Git repository registration, Cortex will try to automatically detect which corresponding Snyk project is associated with a given entity.
Definition:snyk (==/!=) null
Example
An initial level in a security Scorecard might include a rule to make sure entities are associated with Snyk project - without this, Cortex won't pick up data about issues from Snyk.
Setting a snyk != null rule can also serve as a secondary check to confirm an entity is synced properly with Snyk and is reporting frequently.
The Scorecard's top level might include a rule to ensure that entities have a low number of Snyk issues.
To indicate progress over time and incentivize further improvement, you could set an intermediate rule with a slightly higher count of Snyk issues.
If an entity has a Snyk project set and only one or two issues, it will achieve the highest level by these standards. An entity with a Snyk project set and three or four issues will achieve the next-highest level, while an entity with a Snyk project set and five or more issues will achieve the lowest level. Entities without a Snyk project will not achieve any level, regardless of how many issues they have.
You can also write more complex rules to set more specific standards. Instead of setting a rule for a moderate number of Snyk issues, you could check that entities have no outstanding critical issues.
Snyk does not currently support aggregated issues in regions outside of the U.S.A. Please use .issues() rather than .numOfIssues() if in a non-U.S.A. region.
View integration logs
This feature is available to Cortex cloud customers.
Cortex fetches issues and vulnerabilities from Snyk and Git sources in real time. Depending on the volume of data, it may take additional time for the data to load on an entity page.
The following options are available to get assistance from the Cortex Customer Engineering team:
Email: [email protected], or open a support ticket in the in app Resource Center
Slack: Users with a connected Slack channel will have a workflow added to their account. From here, you can either @CortexTechnicalSupport or add a :ticket: reaction to a question in Slack, and the team will respond directly.
Don’t have a Slack channel? Talk with your Customer Success Manager.
ClickUp is a project management tool that combines tasks, document collaboration, and issue management in a single platform.
Integrating ClickUp with Cortex allows you to:
View task information directly on entity pages in Cortex
Create ClickUp tasks based on Initiatives directly from Cortex
Map ClickUp identities to users in Cortex
View open ClickUp tasks in the
Create that track progress and drive alignment on projects involving your ClickUp tasks
How to configure ClickUp with Cortex
Prerequisites
Before getting started:
Create a .
Configure the integration in Cortex
In Cortex, navigate to the .
Click Integrations from the main nav. Search for and select ClickUp.
Click Add configuration.
If you’ve set everything up correctly, you’ll see the option to Remove Integration in settings.
You can also use the Test configuration button to confirm that the configuration was successful. If your configuration is valid, you’ll see a banner that says “Configuration is valid. If you see issues, please see documentation or reach out to Cortex support.”
Note that mapping options will not appear in Cortex for users who have not finished user registration in ClickUp. If a user is partially registered, Cortex will filter them out of the mapping page.
How to connect Cortex entities to ClickUp
Auto discovery of spaces, folders, and tags
By default, Cortex will use the (e.g. my-entity) as the "best guess" for ClickUp space, folder, or tag. For example, if your Cortex tag is my-entity, then the corresponding space, folder, or tag in ClickUp should also be my-entity.
If your ClickUp space, folder, or tag don’t cleanly match the Cortex tag, you can override this in the Cortex entity descriptor.
Editing the entity descriptor
You can map any number of ClickUp spaces, folders, and tags to a Cortex entity. Spaces and folders can be mapped by using either ID or name.
You can find your folder ID or space ID in your ClickUp URL: https://app.clickup.com/:workspace_id/v/f/:folder_id/:space_id.
Mapping spaces by ID or name
When mapping spaces, you can use the ID or name for the space.
These blocks share the same fields:
Field
Description
Required
Mapping folders by ID or name
When mapping folders, you can use the ID or name for the folder.
Field
Description
Required
Mapping by tags
Cortex also supports mapping entities to ClickUp .
Field
Description
Required
Specify a list for Initiative issues
You can also specify a ClickUp list to store all issues created via Cortex Initiatives. If Use list defined in entity YAML is toggled on in the Initiative issue creation form, Cortex will automatically create tasks in the specified list for a given entity.
If a list is not specified in an entity's YAML and Use list defined in entity YAML option is toggled on in the initiative issue creation form, Cortex will attempt to create a list in the mapped space or folder above.
Define one of these following blocks in an entity descriptor to specify a list for Initiative issues.
Specify list by ID
Field
Description
Required
Specify list by name
Identity mappings
Cortex maps email addresses in your ClickUp instance to email addresses that belong to team members in Cortex. When is set up, users will be able to see their personal on-call status from the developer homepage.
Note that mapping options will not appear in Cortex for users who have not finished user registration in ClickUp. If a user is partially registered, Cortex will filter them out of the mapping page.
Using the ClickUp integration
Entity pages
Integrations - ClickUp
Tasks detected from your ClickUp instance will populate on the Issue tracking page in the entity's sidebar. Each row will show the following information (when available in ClickUp):
Task name (hyperlinked to task in ClickUp)
Project
Assignees
Priority
Initiatives
Initiatives allow you to set deadlines for specific rules or a set of rules in a given Scorecard and send notifications to users about upcoming due dates.
From the Issues tab of an Initiative, you can automatically .
Dev homepage
The ClickUp integration enables Cortex to pull information about tasks into the Dev homepage. You can find open tasks assigned to you under the .
Issues are refreshed every 5 minutes, or you can click Refresh ClickUp tasks to manually refresh issues.
Scorecards and CQL
With the ClickUp integration, you can create Scorecard rules and write CQL queries based on ClickUp tasks.
See more examples in the in Cortex.
List of ClickUp tasks
Get ClickUp tasks meeting the given filter criteria.
Assignees
Created at
View integration logs
This feature is available to Cortex cloud customers.
On the integration settings page, click the Logs tab to view logs from the last 7 days. Learn more in .
Create a task from an Initiative issue
Initiatives allow you to set deadlines for specific rules or a set of rules in a given Scorecard and send notifications to users about upcoming due dates. You can create a ClickUp task from a failing rule in an Initiative. Learn more in .
The issue configuration will apply to all entities that meet the filter criteria. Once an entity is passing the rule, Cortex will automatically close the associated ticket.
Background sync
Cortex conducts a background sync of ClickUp identities every day at 10 a.m. UTC. Pull requests and issues are refreshed every 5 minutes.
Still need help?
The following options are available to get assistance from the Cortex Customer Engineering team:
Email: , or open a support ticket in the in app Resource Center
Slack: Users with a connected Slack channel will have a workflow added to their account. From here, you can either @CortexTechnicalSupport or add a :ticket: reaction to a question in Slack, and the team will respond directly.
Don’t have a Slack channel? Talk with your Customer Success Manager.
Microsoft Teams
Microsoft Teams is a communication and collaboration platform designed to promote greater productivity through messaging and file-sharing tools.
Integrating Microsoft Teams with Cortex allows you to:
Quickly find the relevant MS Teams channel to communicate with the right team, allowing for easier collaboration on projects and faster communication during an incident
Receive actionable directly in MS Teams for Scorecard changes, upcoming Initiatives, weekly summaries of entity performance, and more
Create that enforce standards such as having an MS Teams channel set for projects
How to configure Microsoft Teams with Cortex
This page describes how to integrate Microsoft Teams with Cortex cloud. If you're using a self-managed Cortex instance, you'll need to follow a manual configuration process to use Cortex's app for Microsoft Teams. Follow the .
Step 1: Configure the integration in Cortex
In Cortex, navigate to the .
Click Integrations from the main nav. Search for and select Microsoft Teams.
Click Add configuration.
Permission
Requirements
Description
After authenticating, you will be redirected to the Microsoft Teams integration settings page in Cortex. In the upper right corner of the page, click Test configuration to ensure Microsoft Teams was configured properly.
Step 2: Install the Cortex app for Teams through Microsoft AppSource
On the in Cortex, click the link.
In AppSource, click Get it now. You will be redirected to a page where you can choose whether to download a desktop app or use the web app.
Step 3: Configure a setup policy for Cortex in Teams
MS Teams admins can configure a setup policy for Cortex, can choose whether to automatically download the Cortex app into the personal Teams environments for users, and can choose to pin the app to make it more easily accessible.
If admins do not add a policy to install the Cortex app, then users will need to download the app during setup.
Navigate to the Teams under Teams app > Setup policies.
Click Add to start configuring a setup policy for the Cortex app.
After configuring a policy, navigate to the Installed apps section. Add the Cortex app here.
Limitations
Cortex does not automatically discover MS Teams channels based on a so you must as described below.
How to connect Cortex entities to Microsoft Teams
In order to use this integration's functionality, your MS Teams channels need to be associated with entities in Cortex. Cortex does not automatically discover channels for MS Teams, so you must define them in the .
Editing the entity descriptor
To associate a Microsoft Teams channel with an entity, define a x-cortex-microsoft-teams block in an as shown in the example below.
Defining a Teams channel will provide in Cortex.
Field
Description
Required
Using the Microsoft Teams integration
Viewing Microsoft Teams information across Cortex
: After MS Teams channels are defined in an entity's YAML, MS Teams channels will appear at the top of an entity's overview page in the MST channels block. Channels are also listed in the "Owners" page in an entity's sidebar. You can click any channel name to go directly to that channel in Microsoft Teams.\
You can write CQL queries and Scorecard rules based on Microsoft Teams channels. Learn more under .
Managing Microsoft Teams notifications
After configuring the Microsoft Teams integration, you can choose whether to allow Microsoft Teams notifications for your workspace.
In Cortex under Settings > Notifications, an admin or a user with the Configure workspace notification settings permission can enable or disable the option to receive notifications via MS Teams for each type of notification. Users can also adjust their to control which notifications they receive via MS Teams.
Team, user, and entity MS Teams notifications
Notifications are . DMs and channel notifications are sent from the Cortex app.
User-based notifications are sent to users via a DM from the Cortex app.
Team-based notifications are sent to the MS Teams channel associated with a team.
Entity-based notifications are sent to the MS Teams channel associated with an entity.
Learn more about notifications in the .
Scorecards and CQL
With the Microsoft Teams integration, you can create Scorecard rules and write CQL queries based on Microsoft Teams channels.
See more examples in the in Cortex.
Check if Microsoft Teams channel is set
Checks if a given entity has a registered Teams channel in its entity descriptor.
Definition:microsoftTeams (==/!=) null
Example
For a Scorecard focused on team operations, you can make sure that each team entity has registered a Microsoft Teams channel:
Number of Microsoft Teams channels
Counts the number of Microsoft Teams channels for a given entity.
Channel name
Team name
Total number of members across Microsoft Teams channels registered for the entity
Counts the total number of members across all Microsoft Teams channels registered for a given entity.
Channel name
View integration logs
This feature is available to Cortex cloud customers.
On the integration settings page, click the Logs tab to view logs from the last 7 days. Learn more in .
Privacy Policy
We will retain basic Microsoft Teams metadata like user IDs for the period necessary to fulfill the purposes outlined in our unless a longer retention period is required or permitted by law, or where the Customer Agreement requires or permits specific retention or deletion periods.
Still need help?
The following options are available to get assistance from the Cortex Customer Engineering team:
Email: , or open a support ticket in the in app Resource Center
Slack: Users with a connected Slack channel will have a workflow added to their account. From here, you can either @CortexTechnicalSupport or add a :ticket: reaction to a question in Slack, and the team will respond directly.
Don’t have a Slack channel? Talk with your Customer Success Manager.
Add custom entity types
Every entity you add to your workspace is associated with an entity type. Cortex comes with several built-in entity types, but you can to extend your catalogs.
There are two distinct parts of this process: (via the UI or API), then (via the UI, GitOps, or API).
Want to learn more? Check out the Cortex Academy course on , available to all Cortex customers and POVs.
Opsgenie
Atlassian is deprecating the Opsgenie product and encouraging their customers to migrate to Jira Service Management. Read more about moving from Opsgenie to Jira Service Management on .
Cortex is actively working on developing an integration with Jira Service Management.
is an alert and on-call management platform from Atlassian.
Integrating Opsgenie with Cortex allows you to:
openapi: 3.0.1
info:
title: Payments
description: This is my cool domain.
x-cortex-tag: payments-domain
x-cortex-type: domain
x-cortex-children:
- tag: child-domain-1
- tag: child-service-1
- tag: child-resource-1
openapi: 3.0.1
info:
title: Payments
description: This is my cool domain.
x-cortex-tag: payments-domain
x-cortex-parents:
- tag: parent-domain-1
- tag: parent-domain-2
openapi: 3.0.1
info:
title: Payments
description: This is my cool domain.
x-cortex-tag: payments-domain
x-cortex-type: domain
x-cortex-owners:
- type: GROUP
name: cortexapps/engineering
provider: GITHUB
inheritance: APPEND
openapi: 3.0.1
info:
title: Chat
description: Chat domain.
x-cortex-tag: chat-domain
x-cortex-type: domain
x-cortex-children: # children can be of type service, resource, or domain
- tag: chat-service
- tag: chat-database
x-cortex-parents: # parents can be of type domain only
- tag: payments-domain
- tag: web-domain
x-cortex-owners:
- type: group
name: Support
provider: OKTA
description: Support Team
x-cortex-slack:
channels:
- name: support-team
notificationsEnabled: true
description: This is a description for the support-team Slack channel # optional
x-cortex-oncall:
pagerduty:
id: ASDF2345
type: SCHEDULE
x-cortex-apm:
datadog:
monitors:
- 23456
{
"callerTag": "my-service",
"calleeTag": "braavos",
"path": "/2.0/users/",
"method": "GET",
"description": "ensure user has payment information configured",
"metadata": {
"tags": ["billing", "identity"],
"prod": true
}
}
{
"description": "ensure user has payment information configured",
"metadata":
}
{
"description": "ensure user has payment information configured",
"metadata":
}
# Example for github
relay:
integration: github # can be blank
subtype: # optional, can be blank, see table above for options
alias: alias for configuration from Cortex
env:
GITHUB: "https://github.com"
GITHUB_API: "https://api.github.com"
GITHUB_GRAPHQL_API: "https://api.github.com/graphql"
verbose: false # set to true to enable verbose logging
proxy:
server: http://proxy.example.com:8080
noProxy: proxy.example.com # note localhost is added automatically
certSecretName: my-proxy-ca-pem # name of the secret containing a .pem file with the CA certificate
services:
axon:
image: ghcr.io/cortexapps/cortex-axon-agent:latest
env_file: .env
env:
- GITHUB_API=api.github.com
- GITHUB_GRAPHQL=api.github.com/graphql
command: [
"relay",
"-i", "github",
"-a", "github-relay", # this is the alias you set up in the Cortex UI
# if you are using a Github App token, add the following line
# "-s", "app",
]
services:
axon:
image: ghcr.io/cortexapps/cortex-axon-agent:latest
env_file: .env
env:
- GITHUB_API=https://github.mycompany.com/api/v3
- GITHUB_GRAPHQL=https://github.mycompany.com/api/graphql
command: [
"relay",
"-i", "github",
"-a", "github-relay", # this is the alias you set up in the Cortex UI
# if you are using a Github App token, add the following line
# "-s", "app",
]
services:
axon:
image: ghcr.io/cortexapps/cortex-axon-agent:latest
env_file: .env
env:
- GITHUB_API=https://api.github.com
- GITHUB_GRAPHQL=https://api.github.com/graphql
command: [
"relay",
"-i", "github",
"-a", "github-relay", # this is the alias you set up in the Cortex UI
# if you are using a Github App token, add the following line
# "-s", "app",
]
services:
axon:
image: ghcr.io/cortexapps/cortex-axon-agent:latest
env_file: .env
env:
- GITLAB_API=https://gitlab.com
- GITLAB_TOKEN=<token>
command: [
"relay",
"-i", "gitlab",
"-a", "gitlab-relay", # this is the alias you set up in the Cortex UI
]
image: ghcr.io/cortexapps/cortex-axon-agent:latest
env_file: .env
env:
- BITBUCKET_API=https://api.bitbucket.org
- BITBUCKET_TOKEN=<token>
command: [
"relay",
"-i", "bitbucket",
"-a", "bibucket-relay", # this is the alias you set up in the Cortex UI
]
image: ghcr.io/cortexapps/cortex-axon-agent:latest
env_file: .env
env:
- BITBUCKET_API=https://bitbucket.mycompany.com
- BITBUCKET_USERNAME=<user>
- BITBUCKET_PASSWORD=<password>
command: [
"relay",
"-i", "bitbucket",
"-a", "bibucket-relay", # this is the alias you set up in the Cortex UI
]
image: ghcr.io/cortexapps/cortex-axon-agent:latest
env_file: .env
env:
- JIRA_API=https://jira.mycompany.com
- JIRA_USERNAME:<user>
- JIRA_TOKEN=<token>
command: [
"relay",
"-i", "jira",
"-a", "jira-relay", # this is the alias you set up in the Cortex UI
]
image: ghcr.io/cortexapps/cortex-axon-agent:latest
env_file: .env
env:
- JIRA_API=https://mycompany.atlassian.com
- JIRA_TOKEN=<token>
command: [
"relay",
"-i", "jira",
"-a", "jira-relay", # this is the alias you set up in the Cortex UI
]
image: ghcr.io/cortexapps/cortex-axon-agent:latest
env_file: .env
env:
- SONARQUBE_API=https://sonarqube.mycompany.com
- SONARQUBE_TOKEN=<token>
command: [
"relay",
"-i", "sonarqube",
"-a", "sonarqube-relay", # this is the alias you set up in the Cortex UI
]
image: ghcr.io/cortexapps/cortex-axon-agent:latest
env_file: .env
env:
- PROMETHEUS_API=http://mycompany.prometheus.internal
- PROMETHEUS_USERNAME=<user>
- PROMETHEUS_PASSWORD=<password>
command: [
"relay",
"-i", "prometheus",
"-a", "prometheus-relay", # this is the alias you set up in the Cortex UI
]
In the side panel, click Connect account via Microsoft Teams OAuth. A popup window will appear.
In the pop-up window, follow the prompts to log in to your Microsoft account. The user configuring the integration must accept the permissions listed below:
ChannelSettings.Read.Group
Enables notifications
Team.ReadBasic.All
Enables notifications to teams
TeamMember.Read.Group
Enables Scorecard rule for Teams
Teamwork.Migrate.All
Enables notifications for users/team channels
This will automatically download the app in users' personal Teams environments.
MS Teams admins can also apply the policy to specific users in the Teams admin center under Users > Manage Users.
To view all entity types, go to Catalogs > All Entities then click the Entity types tab.
A Cortex logo appears next to built-in entity types. When you hover over the logo, you will see a "Powered by Cortex" banner:
The other entity types in the list are custom types.
Create custom entity types
You can create custom entity types:
Manually in the Cortex UI
Via the
When creating an entity type, keep in mind that these will ultimately dictate how you import specific entities later on. After creating the type itself, you will be able to create entities of that type (via the UI, API, or GitOps).
To create, edit, and delete entity types, your user or API key must have the Edit entity types permission.
Create entity types in the Cortex UI
In Cortex, navigate to Catalogs > All entities.
Click the Entity types tab, then click Create entity type.\
Configure the form:
Name: Enter a human-readable name that will appear in the catalog for this entity type.
Type: Enter a unique identifier that corresponds to the entity type. This will be used to specify the type defined in the YAML definitions for imported entities.
Description: Optionally, enter a description for the entity type.
At the bottom of the page, click Create.
After saving, the entity type will appear in the Entity types tab under Catalogs > All entities, and you are now able to import entities of that type.
If you want entities of the new entity type to automatically belong to a specific catalog, you can configure the catalog's defined entity types while or you can to update the entity types.
Create entity types via the API
You can create, update, and delete entity types using the .
Learn more about the below.
JSON schema for custom entity types
Entity type definitions require a JSON schema that outlines the attributes that entities should conform to.
Custom entity type definitions are powered by the open-source JSON Schema project.
The JSON schema for a custom entity type ensures consistency and validation when creating entities of that type. The attributes listed under required in the schema must be defined for entities of that type according to the outlined properties.
In the example below, location is required when creating this type of entity, but the schema also includes department as a possible property.
Field
Definition
Required
type
Type of entity and/or required component: array, boolean, integer, null, number, object, or string
Yes
required
Required specs for the entity type
Adding an entity schema for new custom entities
When creating a new entity of the custom type, if the entity type's JSON schema requires certain attributes, you must include the metadata for those attributes on that entity.
Based on the example above, the entity schema format would look like the following:
Add attributes via YAML
If you are following a GitOps workflow, or if you are editing the entity's YAML directly in the Cortex UI, you can update the custom entity's metadata in the YAML.
Based on the example above, the entity YAML would look like the following:
Defining a JSON schema enables visibility on an entity's detail page. The schema and the defined properties will appear under the Metadata section on the entity's overview, making it easy for you to identify key specs.
In the example below, the entity "Sally S" displays metadata for the property "location."
To create custom entities, your user or API key must have the Edit entities permission.
Create custom entities in the Cortex UI
Before creating a custom entity in the UI, make sure you have UI-based editing enabled for this entity type in Settings > GitOps.
In the main nav of Cortex, click Catalogs > All entities.
At the top of the Services page, click +Import entities.
Choose Create entities manually.
Configure the form:
Type: Select your custom entity type.
Entity schema: Enter a JSON schema to define your custom entity.
When you are finished, click Confirm import at the bottom of the page.
Create custom entities in the entity descriptor
Before creating a custom entity via GitOps, make sure you have UI-based editing disabled for this this entity type in .
If your entity is of a custom type, you must specify x-cortex-type and x-cortex-definition.
The x-cortex-definition field is validated against the that you created via the UI or API. If your custom entity type does not have specific requirements, entities of that type still need a non-null definition specified, like x-cortex-definition: {}.
You can create, read, update, and delete entities via the .
To delete entities, your API key must have the Delete entities permission.
Managing custom entities
Edit custom entities
It is possible to edit entities after creating them:
Navigate to the entity's page.
In the upper right corner, click Configure entity.
Make any desired changes.
Note: The only field you cannot edit is the identifier.
At the bottom of the screen, click Save changes.
Add custom entities to catalogs
After an entity is imported or created, it will automatically belong to a catalog based on the entity type criteria set for each catalog. When you create a custom catalog, you can set the entity type criteria.
By default, any custom entity types you create will belong to the Infrastructure catalog. If you do not want the entity type to belong to this catalog, you can add the entity type to a different catalog's definition.
Managing custom entity types
After creating a custom entity type, you can view or edit its schema, view a list of entities of that type, and validate the schema of entities of that type.
View custom entity types
You can view a custom entity type's schema and a list of entities of that type.
Navigate to Catalogs > All entities, then click the Entity types tab.
Click into an entity type.
The schema is displayed on the entity type page.
Click the Entities tab to view a list of entities of that type.
Learn more about the health and incident data columns in .\
Edit custom entity types
Navigate to Catalogs > All entities, then click the Entity types tab.
Click into an entity type.
In the upper right corner, click Edit.
Make changes to your entity type, then at the bottom of the page, click Save.
You cannot edit the entity type's unique identifier.
Validate an entity schema for a custom entity type
Navigate to Catalogs > All entities, then click the Entity types tab.
Click into an entity type.
Click the Schema linter tab.
In the text editor, paste in your entity's JSON schema to verify that it is properly formatted for this entity type.
On the right side of the page, click Show example to see an example of how the schema should be formatted.
If you want to use the example as a starting point, click Copy example, then paste it into the text editor.
In the upper right side of the text editor, click Validate Schema.
Using custom entity types or custom data
In some instances, you may want to use custom data instead of a custom entity type. This is recommended if you need more flexibility for these entity types; they may not always require specific metadata.
While a custom entity type's metadata will appear on the overview of an entity's details page, custom data does not appear there. Instead, it appears in the Custom data sidebar of an entity details page.
It is possible to create an entity type with an empty properties schema:
This entity type will display in the catalogs, but entities of this type won't be validated against certain specs. Such properties can instead be defined using custom data.
A schema is ideal for enforcing static properties across all entities, while custom data allows users to augment and update attributes.
Click Integrations from the main nav. Search for and select Opsgenie.
Configure the Opsgenie integration form:
Subdomain: Enter the subdomain assigned to your Opsgenie instance.
API key: Enter your Opsgenie API key.
Use European service region: Optionally, toggle this setting on to enable the EU region of Opsgenie.
Click Save.
How to connect Cortex entities to Opsgenie
Discovery
By default, Cortex will use the Cortex tag (e.g. my-entity) as the "best guess" value for the backend and service tags on your alerts. For example, if your alert in Opsgenie has the tag backend:my-entity, the alert will be automatically associated with the entity in Cortex with a unique identifier of my-entity.
If your Opsgenie tags don’t cleanly match the Cortex tag, or you use different identifying tags, you can override this in the Cortex entity descriptor.
Entity descriptor
Field
Description
Required
type
Type of alert (in this case, opsgenie)
✓
tag
Type of tag in Opsgenie (e.g. backend)
✓
For example, for the tag different-tag:my-entity-override-tag, the entity descriptor would have different-tag in the tag field and my-entity-override-tag in the value field.
You can add a list of tags to use for lookup. Cortex will use an OR operator when querying Opsgenie (e.g. backend:my-entity OR service:another-value).
The value field also supports wildcards (e.g. value: my-entity*).
Adding a schedule
You can define the following block in an entity descriptor to add an Opsgenie schedule. Cortex supports adding a schedule by ID or UUID. You can add one schedule per entity.
The UUID for the schedule can be found in URL when viewing schedule details by clicking on the schedule name under who is on-call.
Field
Description
Required
type
Opsgenie component being added (in this case, SCHEDULE)
✓
id
Schedule ID or UUID
✓
Ownership
Field
Description
Required
type
Ownership type (in this case, group)
✓
name
Name of the team defined in Opsgenie (**case-sensitive)
✓
Identity mappings
Cortex maps email addresses in your Opsgenie instance to email addresses that belong to team members in Cortex. When identity mapping is set up, users will be able to see their personal on-call status from the developer homepage.
Using the Opsgenie integration
After setting up the integration, Opsgenie information will appear in several places across Cortex.
Viewing on-call information for an entity
On an entity details page, current on-call information from Opsgenie will display in the On-call block.
Escalation policy, the level associated with the policy, and other on-call information will also appear in the entity's sidebar in the "On-call & incidents" page. Owners assigned to each level will also be hyperlinked to the user or team page in Opsgenie.
Viewing recent Opsgenie events
Click Events in an entity's sidebar to view recent events pulled in from Opsgenie.
Viewing on-call information on the dev homepage
The Opsgenie integration enables Cortex to pull on-call information into the on-call block on the Dev homepage. On-call data from Opsgenie is refreshed every 1 minute.
Scorecards and CQL
With the Opsgenie integration, you can create Scorecard rules and write CQL queries based on Opsgenie on-call schedules and alerts.
For a Scorecard focused on maturity or quality, you can use this expression to make sure a given entity has fewer than two alerts in the last month:
You could also refine this rule by specifying priority level:
Entities will pass this rule if they have fewer than 2 alerts with priority level "P1" in the last month.
Number of escalations
Number of escalation tiers in escalation policy.
Definition:oncall.numOfEscalations()
Example
This expression could be used in a Scorecard focused on production readiness or service maturity. For example, you can check that there are at least two tiers in an escalation policy for a given entity, so that if the first on-call does not ack, there is a backup:
While making sure an on-call policy set is a rule that would be defined in a Scorecard's first level, a rule focused on escalation tiers would make more sense in a higher level.
On-call metadata
On-call metadata.
ID
Name
Type
Definition:oncall.details()
Example
To find all entities without a schedule-type on-call registration, you can use this expression in the Query builder:
If you're migrating on-call policies, you could use this rule to check for outdated policies. Let's say, for example, all outdated Opsgenie policies start with "Legacy" in their titles.
Entities with on-call policies that start with "Legacy" will fail, while those with other policy names will pass.
Ownership CQL
All ownership details
A special built-in type that supports a null check or a count check, used to enforce ownership of entities.
Definition:ownership: Ownership | Null
Example
An initial level in a security Scorecard might include a rule to ensure an entity has at least one team as an owner:
All owner details
List of owners, including team members and individual users, for each entity
Definition:ownership.allOwners()
Example
The Scorecard might include a rule to ensure that entity owners all have an email set:
Team details
List of teams for each entity
Definition:ownership.teams(): List<Team>
Example
The Scorecard might include a rule to ensure that an entity owners all have a description and are not archived:
View integration logs
This feature is available to Cortex cloud customers.
The following options are available to get assistance from the Cortex Customer Engineering team:
Email: [email protected], or open a support ticket in the in app Resource Center
Slack: Users with a connected Slack channel will have a workflow added to their account. From here, you can either @CortexTechnicalSupport or add a :ticket: reaction to a question in Slack, and the team will respond directly.
Don’t have a Slack channel? Talk with your Customer Success Manager.
Teams serve as both an entity representing your organization in Cortex and as owners for different entities in the catalogs. Teams offers a centralized place for the most important information about each group, making it easier for everyone to find what they need.
Teams can be assessed via Scorecards, interact with integrations, and leverage custom data. They can also be configured in a hierarchy.
View teams
To view your teams, navigate to Catalogs > Teams.
When you open the , you'll see Mine and All, which denote teams you belong to and all teams at your organization, respectively. The teams that appear under "All" will automatically display as a , whereas those under "Mine" will be listed individually.
View the teams leaderboard
On the right side of the Teams catalog page, see the Scorecard Leaderboard, which highlights the ten best-performing teams within your organization.
The leaderboard is calculated from the average of scores for all entities owned by a team. Change in rank is based on the team's score 7 days ago. You can use the dropdown to select a different Scorecard, allowing you to view the leaderboard based on specific Scorecards.
The leaderboard gamifies entity quality and encourages team members to achieve goals. This creates a culture of accountability, where everyone has visibility into how they're performing.
View an individual team's page
Each team has its own details page, where you can view key details about the team. Click a team from the Teams catalog page to view its details.
At the top of a team details page, you’ll find on-call information, Slack channels, and parent and children teams.
Additional information appears in tabs on the team's details page:
The Overview tab includes:
Vulnerabilities and issues from linked integrations.
How the team is performing across Scorecards. By default, this will show the level that the team’s entities have reached in each Scorecard.
Learn more about the sidebar links in the documentation.
Ownership
Teams not only allow you to collect vital information in a single place, but are also crucial for ownership. 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.
Read more in the .
Creating a team
You can create teams:
By importing them from a connected integration (e.g., Workday, GitHub)
Manually in the Cortex UI
Via the entity descriptor YAML through
Understanding hierarchies
You can configure teams to reflect the actual hierarchy at your organization while creating or importing teams in Cortex. A team can be defined as the parent of one or more teams while also being the child of another team.
When you access the , individual teams and parent teams are displayed by default. Parent teams have an arrow next to their name, indicating that you can expand to view children teams.
In the above example, My Company is a parent team with 7 child teams nested under it.
Create a team
See the tabs below for instructions on each method.
Importing a team from an integration
If you have an existing source of truth for your teams and team members, we recommend importing teams. By integrating with your identity provider at this stage, Cortex will automatically sync team pages with your source of truth so you don't have to update information in more than one place when people join or leave teams.
Each integration syncs teams daily.
You can only import entities from integrations that have already been configured.
Edit teams
It is possible to edit entities after creating them:
Navigate to the entity's page.
In the upper right corner, click Configure entity.
Make any desired changes.
Adding team member roles
You can manually create a team member role:
In Cortex, navigate to .
Click Add role.
In the "Add role" modal, configure the role:
Apply role to team members
You can apply a role only to manually-created team members. Team members who were imported from an identity integration will retain the role that was imported.
To apply a role:
In Cortex, navigate to Catalogs > Teams.
Click into a team.
In the upper right corner, click Configure entity.
Adjusting team settings
Under , there are several settings relating to teams. You can select which identity providers to use to sync teams and team memberships, configure automatic import from Workday, configure entity editing access, and sync or create roles. Learn more in .
Defining ownership
Ownership is a core use case of Cortex, as many organizations seek to establish accurate ownership of services, data, and other entities. Accurate ownership is foundational for accountability, incident response, security reviews, compliance, and developer productivity. Without clear ownership, critical issues can go unresolved and services can fall through the cracks.
Avoid inefficient manual processes: Use Cortex's ownership prediction model to solve entity ownership quickly. Cortex automatically predicts entity owners so your developers don't waste time hunting down the wrong person.
Ownership can be defined by accepting Cortex's automated recommendations for ownership, pulled in from third-party integrations, or defined manually in the Cortex UI. Ownership can also be inherited from an entity's fallback or append configuration.
Ownership drives which users will receive from Cortex, including alerts for on-call changes, when is needed on an assigned entity, when an entity is re-evaluated and its Scorecard changes, and more.
Where to view entity owners
When viewing an entity, the owners appear in the metadata bar on the right side of the page:
Click into the team name to view the team's entity page, including a list of members and a list of entities owned by that team.
You can who will be defined as owners for your entities.
View entities without owners
There are a few ways to determine which of your entities in Cortex don't have owners assigned yet:
Use the to see unowned entities and Cortex's automated recommendations for owners
Learn more about below.
View the , which lists unowned entities
Define owners for entities
Types of owners
You can define owners based on:
A team: The user is a member of a team that is listed as the owner of an entity.
We recommend setting up teams as owners. If you link a group in your YAML file from a different platform (such as Okta), the members of the team will be automatically updated in Cortex if anyone leaves your organization and is removed from your integrated identity provider.
A user email address: The user is listed as the owner of an entity.
Methods for defining ownership
Owners can be defined:
By accepting Cortex's automated recommendations for owners, based on repository activity
By pulling information from third-party integrations in the
Ownership can also be inherited via .
Cortex automated recommendations for ownership
Research preview
Not seeing the results you expect? This is an early version of the Ownership tool. Please send feedback and bug reports to us . Note the following considerations:
Ownership inheritance
Instead of defining ownership individually for every entity in your catalog, you can define ownership at the parent entity level and have that pass down to all of the entity's children. You can configure this in the Cortex UI while entity and adding owners to it, or while .
inheritance can also be defined in the entity descriptor under the x-cortex-owners block, as shown in the example below:
The inheritance type for each owner can be one of APPEND, FALLBACK, or NONE. If not set, inheritance is defaulted to NONE.
APPEND: This owner is appended to the list of owners for all child entities.
FALLBACK: In the case where a child has no valid owners, including fallbacks, this fallback will be assigned as the owner. Note that this only applies to a child entity down the hierarchy; it is not the fallback for the parent domain itself.
NONE
Automatic discovery for AWS
Cortex can automatically discover ownership for your AWS resources using their owner tag. To enable this, make sure that your AWS resources have an owner tag matching the x-cortex-tag of the corresponding Cortex team and enable the Sync ownership from AWS toggle in .
You can pull in all resources from AWS, and Cortex syncs those owners automatically based on their tags in AWS, allowing you to easily keep the resource owners up to date.
Cortex syncs ownership from AWS every day at 6 am UTC.
Remove incorrect owners
To remove incorrect ownership in Cortex, the steps depend on how the ownership was added and your current configuration. Expand the tile below to learn more.
Remove incorrect ownership
If ownership was set via YAML (x-cortex-owners):
Update the x-cortex-owners block in your YAML to reference only the correct teams or individuals. Ensure that all referenced teams actually exist in Cortex.
Viewing entity ownership
View your owned entities
See entities you own directly:
To see a list of entities you own directly, navigate to then click the Mine tab:
Child team visibility
See your enties and entities owned by your team's child teams:
To see a list of entities you own directly and entities that are owned by your team's child teams:
Navigate to .
View a team's owned entities
You can filter the entity list by owner:
Under , click the All tab.
In the upper right corner, click Filter.
View entities owned by all teams within a hierachy
View entites owned by the parent and children teams:
Teams can exist within hierarchies. You can view a list of all entities that are owned by the parent team and all children teams in the hierarchy:
Navigate to the parent team's page in Cortex.
Ownership settings in Cortex
Under , there are several settings relating to teams. Read more about these in the .
Datadog
Datadog is an application performance monitoring platform that provides real-time observability into entities, servers, databases, and tools, providing developers with a comprehensive understanding of their infrastructure as well as the ability to identify areas for improvement.
Cortex is uniquely equipped to augment Datadog's tools, providing greater visibility into your entities. In this guide, you'll learn how to set up the Datadog integration to pull in services and metrics for entities:
Monitors
SLOs
Dependencies
How to configure Datadog with Cortex
Prerequisites
Before getting started, make sure you have created the following:
You can create this in Datadog under Organizational Settings > Applications Key.
Include the following scopes:
Configure the integration in Cortex
In Cortex, navigate to the .
Click Integrations from the main nav. Search for and select Datadog.
Click Add configuration.
After saving your configuration, you are redirected to the Datadog integration settings page in Cortex. In the upper right corner of the page, click Test configuration to ensure Datadog was configured properly.
Configure the integration for multiple Datadog accounts
The Datadog integration has multi-account support. You can add a configuration for each additional by repeating the process above.
Each configuration requires an alias, which Cortex uses to correlate the designated with registrations for various entities. Registrations can also use a default configuration without a listed alias. You can edit aliases and default configurations from the Datadog page in your Cortex settings. Select the edit icon next to a given configuration and toggle Set as default on. If you only have one configuration, it will automatically be set as the default.How to connect Cortex entities to Datadog
How to connect Cortex entities to Datadog
Tag discovery
By default, Cortex will use the (e.g. my-entity) as the "best guess" for Datadog tag. For example, if your Cortex tag is my-entity, then the corresponding tag in Datadog should also be my-entity.
If your Datadog tags don’t cleanly match the Cortex tag, you can override this in the Cortex entity descriptor.
Import entities from Datadog
See the for instructions on importing entities.
Editing the entity descriptor
You can use service tags to connect Datadog services to Cortex entities.
Field
Description
Required
These tags are used to "discover" your monitors and SLOs. Cortex will find monitors and SLOs by querying tag:value OR tag:value2 ...
If you want to hard code and/or override discovery, you can define a monitor or SLOs block in the entity descriptor, as described below.
Monitors and SLOs
Adding monitors let you see information about their current status directly from a catalog - via the Monitors column - and under the Operations section of an entity page. You can find your monitors from Datadog's .
The ID of a monitor is found in the URL when you click on a monitor in your Datadog dashboard i.e., https://app.datadoghq.com/monitors/****.
Like monitors, Datadog SLOs can be found in the Operations section of an entity page. You can find the SLOs for your instance on Datadog's .
The ID for the SLO can be found in the URL when you click on an SLO in the Datadog dashboard. For example, https://app.datadoghq.com/slo?slo_id=****&timeframe=7d&tab=status_and_history.
Monitors and SLOs have the same field definitions.
Field
Description
Required
Dependency mapping
Cortex automatically syncs dependencies from Datadog's , using the entity identifier (x-cortex-tag) to map entities found in the Service Map.
The relationships Cortex discovers through the integration will feed directly into the , so you can easily visualize the connections between your entities.
If you have two entities - for example, entity-one and entity-two - that have a dependency edge in Datadog's Service Map, both entities should exist in Cortex with the same identifiers ().
You can override this by where tag = entity and value = entity name in Datadog Service Map.
If the Cortex tag does not exactly match the entity identifier in Datadog, the dependencies will not automatically sync. You can override automatic discovery by defining values in the entity descriptor.
You can connect an APM service for dependency mapping in the entity descriptor:
Using the Datadog integration
View Datadog monitors and SLOs on entity pages
With the Datadog integration, you'll be able to find monitors and SLOs on an entity's home page. High-level information about monitors and SLOs appears in the Overview tab.
Click Monitoring in the entity's sidebar to see more detailed data about both monitors and SLOS. Both sections display tags for Pass, Fail, Warning, and No Data for each monitor or SLO.
The SLOs column shows each SLO, its target(s), the current value for that entity, its status. and the period of time the SLO is being calculated for. For example, if the time listed is "7 days ago," then the SLO is looking at the time range starting 7 days ago to now..
The Monitors column shows the title for each monitor, its query (if available), and its status.
Clicking any block with a nonzero value will open a modal with more detailed information. The monitor modals will list all monitors with the applicable status. The SLO modals will also display targets for each SLO that is passing or failing.
Scorecards and CQL
With the Datadog integration, you can create Scorecard rules and write CQL queries based on Datadog metrics, monitors, and SLOS.
See more examples in the in Cortex.
You can read more about Datadog's and in their docs.
Metrics
from Datadog.
Metric
Timestamp
Monitors
Monitors associated with a given entity via ID or tags. You can use these data to check whether an entity has monitors associated with it, or whether an entity has the right types of monitors.
Created at
Creator email
SLOs
SLOs associated with a given entity via ID or tags. You can use these data to check whether an entity has SLOs associated with it and if those SLOs are passing.
History
ID
Discovery audit
Cortex will pull recent changes from your Datadog environment into the . Here, you can find new entities in Datadog that have not been imported into the catalog - these will have the tag New APM Resource - as well as entities in the catalog that no longer exist in Datadog - these will have the tag APM Resource Not Detected.
View integration logs
This feature is available to Cortex cloud customers.
On the integration settings page, click the Logs tab to view logs from the last 7 days. Learn more in .
Background sync
The dependency sync runs automatically each day at 12 a.m. UTC, and can be run manually via the in the .
FAQs and troubleshooting
Can I set a Scorecard rule to monitor Datadog monitors/SLOs based on tags?
Yes, you can that allow Cortex to discover your SLOs and monitors, and use these tags in Scorecard rules.
How does Datadog work with other dependency sources?
When leveraging multiple dependency sources such as Datadog and a catalog entity's YAML, all the sources would be merged together and Cortex will de-duplicate the dependencies.
For example, if an entity YAML indicates X → Y and Datadog indicates X → Y and X → Z, the entity will display two edges presented as X → Y and X → Z.
Workday
Workday is cloud-based enterprise software that unifies finance and workforce management in a single platform. Integrate Workday with Cortex to manage teams and hierarchies, enforce ownership, and drive operational excellence.
How to configure Workday with Cortex
Step 1: Generate an ownership report in Workday
Depending on how you want to manage teams and the corresponding hierarchy, you can choose one of the following options:
Manage teams based on Workday supervisory organizations
Manage teams based on Workday teams
The required fields in the report differ depending on which option you choose. See the tabs below for instructions.
Your report will need the following fields:
email: Email address for employee. Use the same address that employees will use to access Cortex.
employeeId: Unique ID for each employee.
Step 2: Configure the integration in Cortex
In Cortex, navigate to the :
Click Integrations from the main nav. Search for and select Workday.
Click Add configuration.
Step 3: Configure the report mappings
After saving the configuration, you can configure how you want the fields to map to different elements in Cortex. The options available in each dropdown menu will mirror the fields included when generating the ownership report.
Configure the mappings:
Employee Attributes: Map report fields that pertain to employees, including the following:
Employee ID
Configure the hierarchy fields for auto-importing Workday teams
If you choose to , you must also configure the hierarchy fields mappings:
Field on parent team: The value selected becomes a parent team for value selected in Field on child team.
Is List: Toggle on when an entry for the parent field is a parent to multiple teams.
Field on child team: The value selected is defined as child team.
Note that you must in order to import hierarchies.
How to connect Cortex entities to Workday
Discovery
By default, Cortex will use the (e.g. my-entity) as the "best guess" for Workday team. For example, if your Cortex tag is my-entity, then the corresponding name in Workday should also be my-entity.
If your Workday teams don’t cleanly match the Cortex tag, you can override this in the Cortex entity descriptor.
Note: The team name is case-sensitive and should be exactly the same as in the report's teamDisplayName or teamName field.
Automatic import of teams
You can choose to automatically import discovered teams and team relationships from Workday into Cortex. Before enabling auto import, make sure your Workday report includes the managerEmail field to ensure that team relationships are imported.
Navigate to in Cortex.
Under Enabled identity providers, make sure the box is checked next to Workday.
Under Enable auto import of teams, click the toggle next to Auto import teams to turn this setting on.
The next automatic import will occur when the background at 9 a.m. UTC.
If an entity already exists with a tag that matches the tag of a Workday team that you are importing, Cortex automatically adds a -team suffix to the Workday team's .
For example, if payments exists as a Cortex tag in Cortex, then you import a Payments team from Workday, Cortex will import the team's tag as payments-team.
Manually trigger team import
You can also manually trigger this sync:
Navigate to in Cortex.
Click Create team.
In the upper left corner, click Sync teams.
Entity descriptor
Field
Description
Required
Using the Workday integration
Entity pages
Once the integration is set up, Cortex will automatically import and structure your team hierarchy. Any teams imported from Workday will appear with a description: "Automatically created by Cortex".
On each team's details page, any team members Cortex detects will populate under the Members tab. If you included the "Role" field in your Workday report, members' roles will appear in a badge next to their names.
Scorecards and CQL
All ownership details
A special built-in type that supports a null check or a count check, used to enforce ownership of entities.
Definition:ownership: Ownership | Null
Example
An initial level in a security Scorecard might include a rule to ensure an entity has at least one team as an owner:
All owner details
List of owners, including team members and individual users, for each entity
Definition:ownership.allOwners()
Example
The Scorecard might include a rule to ensure that entity owners all have an email set:
Team details
List of teams for each entity
Definition:ownership.teams(): List<Team>
Example
The Scorecard might include a rule to ensure that an entity owners all have a description and are not archived:
View integration logs
This feature is available to Cortex cloud customers.
On the integration settings page, click the Logs tab to view logs from the last 7 days. Learn more in .
Background sync
Cortex syncs teams from the report every day at 9 a.m. UTC.
You can sync teams manually at any time by clicking the Sync teams for Workday button from in Cortex. Doing so will not auto-import teams.
Limitations
Cortex does not support hierarchies with cycles. For example, let's say Employee A is on the platform team, Employee B is on the frontend team, and both report to Manager C on the engineering team. If Manager C reported to someone on the platform team, that would create a cycle between the platform and engineering teams.
Still need help?
The following options are available to get assistance from the Cortex Customer Engineering team:
Email: , or open a support ticket in the in app Resource Center
Slack: Users with a connected Slack channel will have a workflow added to their account. From here, you can either @CortexTechnicalSupport or add a :ticket: reaction to a question in Slack, and the team will respond directly.
Don’t have a Slack channel? Talk with your Customer Success Manager.
Cortex MCP
is a Model Context Protocol server that provides access to the . It uses relevant context from your workspace, ensuring awareness of your system's structure when answering your questions.
You can query information in natural language, powering faster decisions and efficient processes. For example:
Who is the right person to handle an incident with backend-server?
Show me the services that belong to the platform engineering team
x-cortex-microsoft-teams:
channels:
- name: team-engineering
teamName: engineering
description: This is a description for the engineering channel in Teams.
notificationsEnabled: true
Display icon: Select an icon to appear alongside the entity type throughout the app.
Schema: Define a JSON schema that will be used to validate the x-cortex-validation block of a given entity’s YAML.
This can be used to enforce certain attributes about entities, such as a region or version number. Attributes defined in the schema will be required when creating an entity of that type, which can then be validated in Scorecards. Learn more under JSON schema for custom entity types.
In the example screen shot below, we’ve created a custom entity type called Employee — this is what we’ll use to represent individuals at our organization. In the schema section, you can see that each profile is required to include an employee’s location. This means every time you create an entity of type "Employee," you will define the employee's location.\
For example, if the entity type's schema requires location and department, your new entity's schema might look like this:\
Click Show example above the schema to view an example of how the entity's schema should be formatted. To use the example as a starting point, click Copy example then paste it into the Entity schema text editor.
Owners: Define ownership for your entity. We recommend selecting team owners to keep your ownership information up-to-date through any future personnel changes.
Links: Add links to external documentation, such as runbooks, docs, logs, or custom categories.
Parents: Define parent domains. This is where you configure the hierarchy for your entity. These can be visualized in the relationship graph.
Dependencies: Select entities that this entity depends on. These can be visualized in the relationship graph.
On-call: Configure on-call information.
Repository: Select the repository associated with this entity.
On the right, enable the toggle next to Aggregate children scores to include child entities in the Scorecard overview.
A list of recent events associated with this team, such as alerts from PagerDuty.
The Dependencies tab shows any incoming or outgoing dependencies associated with this team.
The Team members tab includes a list of all team members and their roles. When available, Cortex will also pull in profile photos from your Git provider.
The Entities tab shows a list of all entities that the team owns.
Via the
Supported integrations
Teams from the following integrations can be imported:
After configuring an integration that includes teams, follow these steps to import teams:
In Cortex, navigate to Catalogs > All entities, then click Import entities.
Choose Import discovered entities.
Select the integration to import from.
On the following page, after the integration sync is complete, a list of entities from the integration are displayed. Check the boxes next to any entities you want to import.
If you have a large volume of entites, click Filter in the upper right corner of the results list to select and apply entity type filters.
At the bottom of the page, click Next step.
Edit the details for the entity:
Type: Select Team.
Name: Enter a human readable name for your team.
If you selected more than one entity: After the first entity is configured, click the name of the next entity on the right to navigate to the detail editor for that entity.
Click Confirm import.
Manually creating teams
If you don’t have an identity provider with updated team information, you can create a team manually within Cortex. Because teams are important for effective ownership, it's recommended that you create teams in Cortex even if you don't have a single source of truth for team information.
In Cortex, navigate to Catalogs > Teams, then click Import teams.
Choose Create entities manually.
Configure the form:
Configure the team details:
Type: Select Team.
Name: Enter a human readable name for your team.
Click Confirm import.
Once you've created a team, you can view it on the Teams page within the hierarchy. If you haven't added parents or children, you can disable View as hierarchy to see the list of all teams.
Adding Cortex-managed teams
You can manually create teams in Cortex and define them in the entity descriptor.
You can also define teams as owners via entity descriptors. See the Ownership documentation for more information.
Team entity descriptor
If your entity is a team, you must specify x-cortex-type as team.
The x-cortex-team tag has two main sections: groups and members.
Adding groups to the team entity descriptor
Use groups to link your team entity with a team on a different platform that you have integrated with Cortex. You can only link one group to a team entity.
For example, you can specify:
Under groups, when you specify okta-security-team, your team will contain all the members from your okta-security-team.
Now, if you specify the okta-security-team in your on any of your other entities, they will automatically recognize example-team as a team that owns their entity.
Adding team members to the team entity descriptor
members can be used to add individual members to your team when you have a use case for a team entity that doesn't correspond exactly to a team on one of your integrations. Members support roles. For example, the following entity includes a member who has the product-manager role and a member who has both the engineering-manager role and manager role:
After specifying the YAML example above, your team now will contain Product Manager and Engineering Manager. If [email protected] or [email protected] were to correspond with the email of an actual account in Cortex, they would start seeing example-team being displayed as a team that they're a part of (i.e., it would start showing up in their Mine tab in catalogs that contain teams).
must be defined for your workspace in your , under the "Teams" tab.
The role field in member is optional. In order to be considered valid, a team must have a non-empty group.
Team children
You can define a list of other teams as children, allowing you to represent a hierarchy of how your teams are modeled across your workspace, using the x-cortex-children tag.
This hierarchy is available to look at in the Teams catalog page.
The hierarchy of entities in Cortex is based on that hierarchy being defined in the entity's YAML file; Cortex does not set hierarchies based on a YAML file's location in your repository.
Team parents
Team children allow you to define the team relationship from the top-down, but in some cases it may be easier to define the team hierarchy from the bottom-up. For these cases, x-cortex-parents can be added to any entity's YAML to define its parents.
Example cortex.yaml
Note: the YAML definition for a team entity can take file names other than cortex.yaml or cortex.yml; see the .
Creating teams via the API
You can create, update, and delete teams using the .
Note: The only field you cannot edit is the identifier.
At the bottom of the screen, click Save changes.
Role name: Enter the role's name.
Tag: The tag - a unique identifier for the role - automatically populates based on the role name.
Role description: Enter a description of the role.
Enable notifications by default: If notifications are enabled, members with this role will receive relevant updates on Scorecards, Initiatives, and more.
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 will automatically create a team. The team will include a label that says Automatically created by Cortex.
This feature is supported for entities associated with a repository in GitHub, GitLab, or Azure DevOps. Mapping is done on 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 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 a repository and automatically recommends a team owner for entities that do not have an owner.
If an entity does not have an owner and Cortex has recommendations for who the owner should be, it will be flagged in the ownership tool under Tools > Ownership, in the "Owners" section of an entity details page overview, in the "Owners" sidebar link on an entity details page, and it will appear during the import process when adding entities.
To review and assign ownership across all unowned entities:
In the main nav of Cortex, click Tools > Ownership.
A list of recommendations for ownership is displayed.\
Review and accept the recommended owners.
To apply all recommended owners: Ensure the checkboxes for all entities are selected, then at the top of the list, click Accept recommendations.
To apply selected owners: On the left side of the list, check the box next to the entities whose recommended owners you want to accept. When you are finished selecting, click Accept recommendations at the top of the list.
Review ownership recommendations per entity
Users can accept ownership recommendations for an entity if they have edit access for that specific entity, and if UI editing is enabled for that entity type under Settings > GitOps.
On an entity details page next to the "Owners" field, click Recommendations.
Review the suggested owners. To accept a recommendation, check the box next to the recommended owner then click Add owners.
Define owners in the entity descriptor
The x-cortex-owners field allows you to define a list of owners of type email or group.
Cortex recognizes groups from the following integrations:
Search for and select the entity whose ownership you want to edit.
In the upper right corner of the entity's page, click Configure entity.
If this option isn't displayed, make sure you have .
Click the Owners tab, then click +Add next to Teams or Users.
Add team:
Select a team from the dropdown menu, then click Add.
: This owner owns the domain, but not necessarily any of its children (no inheritance).
If you are using GitOps, make sure the YAML is updated and merged to your main branch, then allow Cortex to re-sync. This will update the ownership in the UI to match your YAML.
If ownership was added via API:
Use the to completely replace the entity YAML, or the to remove one or more owner and not change the rest of the entity YAML.
If ownership is inherited from a domain or parent:
Check if the entity is a child of a domain or group with ownership inheritance enabled. If so, the parent’s owners may be appended to the entity.
To remove inherited owners, edit the domain or parent’s owner inheritance setting (e.g., change from Append to None).
The list defaults to displaying the "Mine" tab, showing only the entities you own.
At the top of the list, click Display.
Enable the toggle next to Include child teams.\
Click Done.
In the left side of the filter modal, click Teams. Select teams from the dropdown, then click Apply at the bottom.
Click the
Entities
tab.
Click Display, then enable the toggle next to Inherited Children.\
While viewing owned entities, click Display then add inherited children to the view.
Click Done.
The list will now display all entities owned by the parent and its children teams. Note that this setting does not persist when you navigate away from the page.
You can create this in Datadog under Organizational Settings > API Key.
Configure the Datadog integration form:
Account alias: Enter a name that Cortex will associate this configuration with.
App key: Enter the application key you generated in Datadog.
This key appears under the Key column in Datadog while viewing your list of Application Keys.\
API key: Enter the API key you generated in Datadog.
Region: Select your from the dropdown.
Custom subdomain: Enter the custom subdomain for your Datadog instance.
This field only takes the subdomain, not the entire URL. For example, this field would take cortex-docs from https://cortex-docs.datadoghq.com.
Environments: Optionally, enter environment tags for Datadog entities.
If you set an environment tag here, make sure to set the to match.
Click Save.
Alias for the configuration in Cortex (only needed if you have opted into multi-account support)
Definition:datadog.metrics(query: Text, lookback: Duration, alias: Text | Null)
Example
You can use the datadog.metrics() expression to evaluate the health of your entities in a Scorecard:
This rule makes sure that a given entity's average CPU usage is less than 10% over the last two days.
Creator name
Name
Overall state
Query
Tags
URL
Definition:datadog.monitors()
Example
For a Scorecard focused on operational maturity, this expression can be used to make sure an entity has at least one Datadog monitor set up:
Name
Operation
Remaining budget
SLI value
Datum
Timeseries
SLO target
Source
Thresholds
Name
Threshold
Definition:slos()
Examples
For a Scorecard focused on operational maturity, this expression can be used to make sure an entity has associated SLOs in Datadog:
This rule checks that there is at least one SLO is set up. While this rule makes sense in a Scorecard's first level, a rule checking the status of the SLO would make sense in a higher level:
Entities will pass this rule if all SLOs associated with it have "passing" status.
tag
Tag for the project in Datadog
✓
value
Value for the project; Cortex will find monitors and SLOs by querying tag:value OR tag:value2 ...
✓
id
Datadog ID for the monitor or SLO
✓
alias
Alias for the configuration in Cortex (only needed if you have opted into multi-account support)
firstName: Employee first name. This will be displayed in Cortex.
lastName: Employee last name. This will be displayed in Cortex.
employeeRole(optional): Employee role. This will be displayed in Cortex.
employeeSupervisoryOrgId: The ID for the supervisory organization that the employee is in. Cortex uses this field to group employees.
teamDisplayName: A display name for individual teams based on the employeeSupervisoryOrgId; this should be the same across all employees who belong to the same supervisory org. This will become the Cortex team name and tag.
managerEmail: Email address for the employee's manager. If Cortex detects an employee with the same email as the managerEmail, that employee will be added to the team with a "Manager" role.
teamSupervisoryOrgId: The supervisory org ID for the team that the employee is part of. The organization registered in this field will become a "parent" in the team hierarchy, while the org registered in employeeSupervisoryOrgId will become a "child" in the hierarchy.
teamListKey (for One Employee - Multiple Teams): Key for the list of teams associated with a given user.
Any changes to the employeeSupervisoryOrgId will result in the creation of a new team because this field is how Cortex identifies teams.
Your report will need the following fields:
email: Email address for employee. Use the same address that employees will use to access Cortex.
employeeId: Unique ID for each employee.
firstName: Employee first name. This will be displayed in Cortex.
lastName: Employee last name. This will be displayed in Cortex.
employeeRole(optional): Employee role. This will be displayed in Cortex.
teamName: Team name for employee. This field is what we use to group employees into teams in Cortex.
teamDisplayName(optional): Display name for the team. This will be used for the title and the tag for any teams imported from Workday at time of import. If not included, teamName will be used instead. This should be the same for all employees on the same team.
managerEmail: Email address for the employee's manager. Cortex uses this field to create team hierarchies. If Cortex detects an employee with the same email as the managerEmail, that employee will be added to the team with a "Manager" role.
Omit this field if you do not want to auto-import teams and the corresponding hierarchy from Workday.
Any changes to the teamName will result in the creation of a new team because this field is how Cortex identifies teams.
Configure the Workday integration form:
Username: Enter the username associated with the Workday account used to generate the ownership report.
Password: Enter the password for the Workday username.
Ownership report URL: Enter the URL for the ownership report you generated.
Provide the base report URL. Do not include query parameters in the URL. If necessary, Cortex will append ?format=json when making requests.
Click Save.
Email
First Name
Last Name
Role (optional)
Imports employees' roles and populates a badge that appears next to an employee's name.
Manager Email
When added, lists the corresponding manager for a given employee. The report should also include an entry for the manager to populate the field.
Team Attributes: Map report fields that pertain to employees' teams.
Team type: Select whether to map the fields using One Employee - One Team or One Employee - Multiple Teams.
The One Employee - One Team configuration is best if your report includes employees who belong to a single team. The One Employee - Multiple Teams configuration is recommended if employees have a list of teams they belong to. This is best if you are configuring the integration based on and/or if users manage teams they belong to.
If using One Employee - One Team:
Team ID: Enter the team ID. New teams are imported based on this ID. If the identifier (i.e. teamName) changes, Cortex will create a new team.
Team Name: Enter a display name for the team in Cortex. Cortex will update this name if changes are detected in Workday.
If using One Employee - Multiple Teams:
Team List Key: Enter the list key for the list that contains teams you want imported into Cortex for a given employee entry. This requires the teamListKey field in the Workday report. The teamListKey should be a list of objects, where each object has at least teamName and teamId properties:
At the bottom of the screen, click Save.
Root Team IDs: The ID for the team you expect to be at the top of the hierarchy.
If set, Cortex will use this to break cycles that may be in the hierarchy.
The source of the team (in this case, it was a Cortex-created team)
Use Cortex MCP with Devin
Cortex MCP is available in the Devin marketplace. Cortex MCP identifies the work that needs to be done, and Devin autonomously performs the work — creating PRs, updating documentation, and refactoring code — to bring your services into compliance. Learn more in our blog.
Cortex MCP demonstration video
See a demonstration of how you can use Cortex MCP to get quick answers without having to switch tools:
How to configure Cortex MCP
You can host the MCP server locally, or you can use a remote implementation.
Paid subscriptions to MCP clients generally give you a larger context window, but the free versions of these clients should suffice.
If hosting the MCP server locally, you should also have installed and running.
Configure the MCP
Step 1: Install Cortex MCP
Run the following command:
Step 2: Configure your MCP client
Looking for IDE-specific setup? Our README has detailed configuration steps for Claude Desktop, Cursor, VS Code, and other MCP clients.
Update your MCP client's configuration file. Make sure to include your Cortex access token value for the CORTEX_API_TOKEN argument:
Alternate option: Create and configure the file in terminal
Alternatively, you could enter the following in terminal to create and configure the file:
Benefits of using the remote MCP
The remote Cortex MCP uses the public cortex-mcp package as a dependency, installed from GitHub. This configuration of the Cortex MCP enables:
Faster setup: No need to install or maintain local binaries.
Updated context: Cortex automatically keeps the service aligned with the latest MCP specification.
After updating your configuration, restart your MCP client.
Self-managed additional configuration
If you are a self-managed Cortex customer, you must also set CORTEX_API_BASE_URL=https:// alongside the CORTEX_API_TOKEN variable.
Self-managed configuration example
Set the CORTEX_API_BASE_URL to your backend host URL.
If you are running a self-hosted instance with CA-signed certificates, you may need to mount them to the container as seen in the example below:
Using Cortex MCP
Start a new chat
In your MCP client, ask a question about your Cortex workspace. The client will use the Cortex API to provide detailed answers based on your data.
For example:
You might ask what's going on with a specific Scorecard. The MCP client will respond with an overview, Scorecard structure information, a progress summary, and suggestions for next steps.
You could ask about the custom data that an entity has. The MCP client will respond with that entity's custom data and information about when it was created:
You could ask about the dependencies an entity has. The MCP client will respond with a list of incoming and outgoing dependencies:
getMyWorkspace: this tool supports the "Mine" capabilities that are available in the Cortex UI. With this tool, you can ask questions like, "Show me my Cortex entities" or "Tell me how my entities are performing against the Production Readiness Scorecard." This tool is enabled by default.
Eng Intelligence metrics in MCP
Eng Intelligence metrics are also available to Cortex MCP as part of the AI Chief of Staff feature. This brings metric data directly into the Cortex MCP, enabling richer AI-assisted insights, not only into engineering performance, but across your entire Cortex ecosystem. It allows you to be a more proactive leader and enables more data-driven planning sessions.
To query Eng Intelligence metrics in MCP:
Ensure you have the latest Cortex MCP version configured in your environment. Once enabled, the MCP will automatically include endpoints for Eng Intelligence metrics. You can then query Eng Intelligence metrics alongside ownership, Scorecard, and Initiative information. For example:
Evaluate my DORA metric performance in Q3. Highlight where the team is performing well and bring areas of improvement to my attention
Which services have concerning MTTR trends, and what scorecard gaps are contributing?
Recommend initiatives and scorecard changes I could consider to address my upward trend in incidents
Review last quarter’s performance against our goals, identify the top three bottlenecks, and suggest changes to our scorecards to address them
Is there a correlation between my PR size and how fast we ship?
Learn how the AI Chief of Staff helps leaders move from viewing data to acting on it:
Enable and disable provided tools
Before submitting questions or commands, you may want to limit the number of provided tools being used by the MCP provider. For example, you might only want to use the MCP to ask about entities but you do not want to allow questions about Scorecards.
In the settings of your MCP client, it is possible to limit which Cortex tools are being used.
Claude example
For example, in Claude desktop:
Navigate to Settings > Connectors > Cortex > 3 dots icon > Tools and Settings.
Under PROVIDED TOOLS, toggle off the options you don't need.
Restart Claude.
Navigate to your Claude chat and enter commands.
Crafting effective MCP prompts
Best practices
The Cortex MCP becomes more powerful when using it becomes second nature to your teams. That shift happens when you have developed prompts that fit your specific role, answer your recurring questions, and surface information in the exact moments you need it. Follow these best practices when crafting prompts:
Be specific: Instead of "tell me about services," you could say, "Show me all critical services failing the Production Readiness Scorecard." This will give you more actionable information.
Combine multiple questions when context helps: The MCP handles complex prompts like "Who owns orders-api, when was it last deployed, and are there any open incidents?" You get richer context in response to one question instead of piecing together three separate queries.
Reference your organization's specific constructs: If you've defined custom Scorecards or Initiatives in Cortex, reference them by name. The MCP understands your organization's specific standards and can query against them directly.
Use follow-up questions to drill down: Start broad, then go narrow. "Show me services with failing Scorecards" followed by "What specific checks is checkout-service failing?" moves you from landscape view to action items.
Build a library of your most-used prompts: If you ask the same question every Monday morning, save it. Some teams maintain shared prompt libraries so everyone can benefit from patterns that work. See the below for ideas.
MCP Prompt Library
We've collated the most effective prompt patterns we've seen across different roles and workflows to build out a library of prompts for engineers, engineering leaders, platform engineers, and SREs. See Cortex MCP Prompt Library for the full list of prompts.
See the beta pages to learn more about the Chief of Staff, which enables the use of Engineering Intelligence metrics in MCP (now available in research preview).
We'd love your feedback!
If you've been using the Cortex MCP, we'd love to hear your direct feedback on the configuration process, the tools available, and how you've been using it. Your feedback helps us improve and expand our capabilities, if you are interested in helping guide our MCP direction, please submit the survey here.
Troubleshooting and FAQ
When I ask a question in my MCP client, why do I see an error that says I hit the maximum length for this chat?
This can happen if you are on the free plan of your MCP client.
Can I make changes via the Cortex MCP?
No, you cannot make changes or write data via the Cortex MCP. The MCP is strictly read-only—it only handles GET requests and cannot modify or write data.
How do I resolve "unauthorized" errors in the MCP?
Ensure that the value of your Cortex API token is valid in your configuration.
How do I resolve "file not found" errors in the MCP?
Ensure that your OpenAPI spec path is correct when mounting.
How do I resolve connection issues with the MCP?
Verify that your Cortex API endpoint is accessible.
How do I resolve a 403 forbidden error in the remote MCP?
Check that you are setting up the remote MCP with a personal access token generated in Cortex. Remote MCP setup requires a PAT, not an API key.
Why might I see an SSL certificate error while using the MCP?
This is most likely caused by an issue within your network. We recommend contacting your organization's infrastructure or security team to troubleshoot.
SonarQube is an open-source platform that empowers developers to write clean and safe code by continuously inspecting code quality and reviewing for bugs, vulnerabilities, and code duplication.
Integrating SonarQube with Cortex allows you to:
Pull in code smells, bugs, code coverage, vulnerabilities, and custom metrics on entity details pages
Create Scorecards that track progress and drive alignment on projects involving your SonarQube projects
This integration is supported for both SonarQube Server and SonarQube Cloud.
How to configure SonarQube with Cortex
Self-hosted prerequisites
If you’re using a self-hosted instance of SonarQube, you’ll need to verify that your Cortex instance is able to reach the SonarQube instance.
If you're unable to directly allowlist our static IP, you can route requests through a secondary proxy in your network that has this IP allowlisted and have that proxy route traffic to your SonarQube instance.
Configure the integration
There are two options for integrating SonarQube: the default configuration method and Cortex Axon Relay, a relay broker allows you to securely connect your on-premises SonarQube data.
Configure SonarQube with the default method
Prerequisites
Before getting started, create a SonarQube user token:
Integrate via custom webhook
If you’re unable to expose your SonarQube instance to be reachable by Cortex, you can set up a . To learn more about SonarQube webhooks, visit their .
How to connect Cortex entities to SonarQube projects
Discovery
By default, Cortex will use the (e.g. my-entity) as the "best guess" for SonarQube component key. For example, if your Cortex tag is my-entity, then the corresponding component key in SonarQube should also be my-entity.
If your SonarQube component key doesn't cleanly match the Cortex tag, you can override this in the Cortex entity descriptor.
If you’re using build-system tooling to push analysis to SonarQube, the plugin (e.g. Gradle, Maven) may be automatically generating a project key that’s different from the repo name.
Connect entities via YAML or the Cortex UI
Connect SonarQube entities via the Cortex UI
Navigate to an in Cortex.
In the upper right corner, click Configure entity.
Cortex only supports one SonarQube project per entity.
Using the SonarQube integration
View SonarQube data on entity pages
Once the integration is established, data from SonarQube will be available in the Code & security page in an as well as under the Overview tab. You can pull in data on code smells, bugs, code coverage, vulnerabilities, and any custom metrics available through Sonar. You can read more about metric definitions in Sonar's .
Metrics
Complexity
Duplications
Scorecards and CQL
With the SonarQube integration, you can create Scorecard rules and write CQL queries based on SonarQube projects.
See more examples in the in Cortex.
Analysis freshness
Duration since the last analysis was uploaded to SonarQube for a given project (with granularity of days).
Definition:sonarqube.freshness()
Example
For a Scorecard focused on operational readiness, you can use this expression to evaluate the freshness of static analysis metrics from SonarQube.
This rule checks that an analysis has been uploaded to SonarQube within the past week, which developers can use to make sure the metrics being pulled aren't stale.
Metric
Query metrics generated by static analysis of your projects and sent to SonarQube:
Alert status
Bugs
Project existence
SonarQube project exists for an entity.
Definition:sonarqube != null
Example
For a Scorecard focused on operational readiness, you can write a rule to make sure an entity has an associated SonarQube project.
Because having a SonarQube project set would be key for an entity to be evaluated via other SonarQube-related expressions, this rule would make sense in a Scorecard's initial level.
Issues
Query issues identified by static analysis of your projects and sent to SonarQube, including bugs, vulnerabilities, code smells, and more. If the statuses are not filled in, they will default to "OPEN" and "REOPENED" statuses to prevent fetching of resolved issues.
This feature is available to Cortex cloud customers.
On the integration settings page, click the Logs tab to view logs from the last 7 days. Learn more in .
FAQs and troubleshooting
Does Cortex support SonarCloud?
Yes. You can integrate with SonarCloud by following the same steps as integrating with SonarQube. In the URL field, use your https://sonarcloud.io/ URL. You can also use multi-account support to add a self-hosted or SonarCloud instance by adding the URL for that instance during configuration.
I’m seeing “Socket timed out when trying to connect to SonarQube” for all of my entities in Scorecards.
This means that Cortex is unable to talk to your SonarQube instance. Make sure that your instance is running and accessible to Cortex.
I’m using Gradle and I’ve verified that my project is in SonarQube, but Cortex is still showing me an error.
Gradle automatically generates a project key which is equal to [$:]$. As a result, automatic discovery won’t work. You’ll need to override the project key in your Cortex .
My project is in Sonar and Cortex is able to talk to SonarQube, but my score isn’t showing up.
Try the following troubleshooting steps:
Make sure the project key in your YAML is exactly the same as the key in SonarQube.
Verify that the scores are in the “default branch” in SonarQube. If your scores are showing up in a branch-a in SonarQube, but your SonarQube default branch is main, Cortex will not be able to retrieve the scores.
Run the following curl command and verify there are metrics showing up in the response:
What if I want to send custom data, but I don't have control over the integration touchpoint?
If you don't have control of or access to the integration touchpoint (for example, if you're using a SonarQube notification webhook) you'll want to use the API to send custom data. You can find information on sending data to a custom data webhook .
Why might I see the SonarQube connection error Component key not found?
For SonarQube (and all integrations), Cortex will map the Cortex tag defined in the cortex.yaml for a given entity. For SonarQube specifically, the tag must exactly match the project ID in SonarQube. If these are not one-to-one, we recommend using the override detailed above to define the proper mapping for project ID and entity name.
Why might I see the error Sonarqube: Fail to request url on my integration page or a validity check failed error while creating a Workflow?
This can happen if your external DNS certificate expired. Ensure that any certificates you're using are valid.
Still need help?
The following options are available to get assistance from the Cortex Customer Engineering team:
Email: , or open a support ticket in the in app Resource Center
Slack: Users with a connected Slack channel will have a workflow added to their account. From here, you can either @CortexTechnicalSupport or add a :ticket: reaction to a question in Slack, and the team will respond directly.
Don’t have a Slack channel? Talk with your Customer Success Manager.
AWS
provides on-demand cloud computing platforms and APIs.
Integrating Cortex with AWS allows you to:
Track AWS entities in the catalog
Automatically discover and track ownership of AWS entities and dependencies
Review and evaluate Scorecards
Reviewing a Scorecard's evaluation gives you insight into patterns across teams or entities, and areas to prioritize for improvement.
When an entity is failing a rule in a Scorecard, Cortex provides the information needed to review and remediate the issue efficiently. From there, teams can . Resolving these failures not only improves the health and maturity of individual entities but also strengthens the overall reliability and compliance posture of the engineering organization.
Scorecard evaluation
Scorecards as code
Once Scorecards are incorporated into your regular engineering workflows, they become production-grade tools. Scorecards set the benchmarks for how your organization defines “good,” which impacts everything from security standards to on-call rotations. Because Scorecards are crucial to achieving and maintaining standards, you may want to employ controlled access and version controlling.
With GitOps editing for Scorecards enabled, you manage Scorecards through , alongside managing the entities in your catalogs. Every Scorecard has its own YAML file. When GitOps is enabled, changes made to Scorecards will appear in .
Learn about the basics in the .
openapi: 3.0.1
info:
title: Sally S
description: Technical writer
x-cortex-tag: employee-sally
x-cortex-type: org-employees
x-cortex-definition:
location: San Diego
department: Engineering
openapi: 3.0.1
info:
title: Payments Team
description: This is my cool team.
x-cortex-tag: payments-team
x-cortex-type: team
x-cortex-owners:
# Groups can be pulled from various integrations
- type: group
name: my-team
provider: CORTEX
description: This is a description for this owner # optional
- type: email
email: [email protected] description: This is a description for this owner # optional
openapi: 3.0.1
info:
title: Payments
description: This is my cool domain.
x-cortex-tag: payments-domain
x-cortex-type: domain
x-cortex-owners:
- type: GROUP
name: cortexapps/engineering
provider: GITHUB
inheritance: APPEND
Members: Select members of your team. Team members will be marked as owners of entities and receive notifications about entities owned by the team if notifications are enabled.
Links: Add links to external documentation, such as runbooks, docs, logs, or custom categories.
Slack channels: Link the team's associated Slack channel. If notifications are configured, the team will receive notifications here.
You must have the Slack integration configured before linking a channel.
Parents and Children: Define parent and children teams. This is where you configure the hierarchy for your entity. These can be visualized in the relationship graph.
On-call: Configure the on-call service associated with this team. When selected, you will see the latest on-call information displayed on the team's details page.
Identifier: This field is auto-populated based on your entity name. It is a unique identifier for your entity. This is also known as the x-cortex-tag.
Description: Enter a description of the team to help others understand its purpose.
Members: Select members of your team. Team members will be marked as owners of entities and receive notifications about entities owned by the team if notifications are enabled.
Links: Add links to external documentation, such as runbooks, docs, logs, or custom categories.
Slack channels: Link the team's associated Slack channel. If notifications are configured, the team will receive notifications here.
You must have the Slack integration configured before linking a channel.
Parents and Children: Define parent and children teams. This is where you configure the hierarchy for your entity. These can be visualized in the relationship graph.
On-call: Configure the on-call service associated with this team. When selected, you will see the latest on-call information displayed on the team's details page.
openapi: 3.0.1
info:
title: Example Team
description: My Cool Team
x-cortex-type: team
x-cortex-tag: example-team
x-cortex-team:
groups:
- name: okta-security-team
provider: OKTA
openapi: 3.0.1
info:
title: Example Team
description: My Cool Team
x-cortex-type: team
x-cortex-tag: example-team
x-cortex-team:
members:
- name: Product Manager
email: [email protected] notificationsEnabled: true
roles:
- tag: product-manager
- name: Engineering Manager
email: [email protected] notificationsEnabled: true
roles:
- tag: engineering-manager
- tag: manager
openapi: 3.0.1
info:
title: Payments
description: This is my cool team.
x-cortex-tag: payments-team
x-cortex-type: team
x-cortex-children:
- tag: child-team-1
- tag: child-team-2
openapi: 3.0.1
info:
title: Payments
description: This is my cool team.
x-cortex-tag: payments-team
x-cortex-type: team
x-cortex-parents:
- tag: parent-team-1
- tag: parent-team-2
openapi: 3.0.1
info:
title: Chat Team
description: Chat team.
x-cortex-tag: chat-team
x-cortex-type: team
x-cortex-team:
groups:
- name: okta-chat-team
provider: OKTA
members:
- name: Product Manager
email: [email protected] notificationsEnabled: true
- name: Engineering Manager
email: [email protected] notificationsEnabled: true
x-cortex-children: # children can be of type team
- tag: chat-infra-team
- tag: chat-sre-team
x-cortex-slack:
channels:
- name: chat-team
notificationsEnabled: true
description: This is a description for the chat-team Slack channel # optional
x-cortex-oncall:
pagerduty:
id: ASDF2345
type: SCHEDULE
Secure access: Tokens and access are managed in your Cortex workspace with security best practices.
Seamless integration: It works out of the box with popular MCP clients like VSCode, Claude Code, and Cursor.
More tools:
The remote MCP implementation includes more tools, such as the query_docs tool that allows you to query Cortex's documentation and knowledge base in natural language. Ask questions like “How do I configure PagerDuty for my Cortex services?” or "How can I use Cortex to drive AI maturity at my org?"
It also includes the ability to add private tools and integrations on top of the public functionality.
Step 1: Add the remote MCP server to your MCP client
Follow the instructions below for Claude, VSCode, or Cursor. Make sure to replace <CORTEX_TOKEN> with the value of the access token you generated in Cortex.
Claude Code
Run the following command to add the Cortex remote MCP server:
VSCode
Add the following configuration to your .vscode/mcp.json file:
Click Integrations from the main nav. Search for and select SonarQube.
Click Add configuration.
Configure the SonarQube integration form:
Account alias: Enter the alias you will use to tie entity registrations to different configuration accounts.
Token: Enter your user token from SonarQube.
SonarQube URL: Enter the URL for your SonarQube instance.
Click Save.
Configure SonarQube with Cortex Axon Relay
See Internally hosted integrations for instructions. Make sure to follow the SonarQube-specific instructions for the docker-compose.yml file.
Click the Code quality link in the sidebar. \
In the center of the page, configure the details for your SonarQube project:
Alias: If you have multiple configurations, select the one that this project is associated with.
Project: Enter the project's name.
Click Save changes.
Editing the entity descriptor
When managing entities via the YAML entity descriptor, you can configure SonarQube projects under the x-cortex-static-analysis block:
Field
Description
Required
project
Project key defined in Sonarqube
Issues
Maintainability
Quality gates
Reliability
Security
Size
Tests
Code freshness
Code coverage
This same rule would work in a security Scorecard - by making sure a SonarQube analysis has been uploaded within the last seven days, you make sure teams are monitoring for compliance to coding rules.
Code smells
Coverage
Duplicated lines
Duplicated lines density
Lines of code
New blocker violations
New bugs
New code smells
New coverage
New security hotspots
New violations
Reliability rating
Security hotspots
Security rating
Security review rating
SQALE rating
Vulnerabilities
Definition:sonarqube.metric("<metric>")
Examples
Development maturity Scorecard
Code coverage
For a Scorecard focused on development maturity, you can set a rule to make sure entities have greater than 80% code coverage.
Developers can then immediately identify entities that are falling behind to make improvements to testing effectiveness. This Scorecard can also give users a more comprehensive sense of how well code is being tested, and where gaps exist.
This rule also serves as a secondary check that a given entity is hooked up to SonarQube and reporting frequently.
Security Scorecard
Vulnerabilities
You can also use the sonarqube.metric("<metric>") expression to write a rule for a security Scorecard, making sure production entities aren't deployed with a high number of security vulnerabilities. In an initial level of a Scorecard, you might write a rule to enforce 2 or less vulnerabilities:
Sonar recommends 0 vulnerabilities to achieve an A rating for Security, so a higher level in your Scorecard could enforce 0 vulnerabilities:
Code coverage
In a security Scorecard, you could also use the following expression to evaluate code coverage. The Sonar way quality gate requires code coverage to be at 80% or higher:
Entities with low code coverage scores are more likely to be vulnerable to attack, so a lower threshold might make sense for certain security Scorecards.
Security hotspots
Rules focused on security hotspots can also make sure entities are operating with minimal security issues. Hotspots highlight a security-sensitive piece of code where the overall application security may not be impacted; Sonar recommends reviewing 100% of hotspots. In the following rule example, you can aim for less than 2 hotspots that need review:
You can write a rule to check that an entity has fewer than 3 major java:S2142 bugs:
Code smells
In an initial level of a Scorecard, you could write a rule to check that an entity has fewer than 5 minor code smells:
In higher levels of the Scorecard, you could verify that the entity has 0 code smells, per Sonar's recommended best practices:
Click Integrations from the main nav. Search for and select AWS.
Click Add configuration.
In the modal, the JSON configuration, Cortex AWS account ID, and External ID are displayed. In the configuration side bar instructions, you will also see the option to copy a starting "Read Only Access" JSON policy. Keep this browser window open, as you will need these in the next steps.
Step 2: Set up an IAM policy in AWS
When using Cloud Control, the role Cortex assumes to get access into your account needs to have read access to all the selected types. This access is included by default in the Read Only Access policy in Cortex, or it can be configured manually for each type.
For each account:
Log in to your AWS Management Console and open the IAM console.
Click Policies, then choose Create policy.
Switch to the JSON editor. In Cortex while configuring AWS, copy the JSON "Read Only Access" starting policy that appears in the in-app instructions. Paste it into the JSON editor.
This policy allows Cortex to list all resources, resource types, and resource tags.
If you choose to configure this manually, rather than using the starting policy provided, insert a valid IAM policy depending on the resource types you'd like to import. For example, if you want to import resources of type AWS::IAM::role, we'll need to have permission to iam:ListRoles, iam:ListAttachedRolePolicies, iam:GetRole, iam:ListAccountAliases and iam:ListRolePolicies.
Click Review Policy, enter a name, then click Create Policy.
This section is specific to cloud-based Cortex accounts. If you are on a self-hosted Cortex instance, please see the AWS account setup guide for self-hosted Cortex.
In AWS, navigate to Roles > Create Role.
For the trusted entity type, select Another AWS account.
In the Account ID field, enter the Cortex AWS account ID that was displayed in Cortex in the earlier steps.
Click Require External ID, then enter the Cortex external ID that was displayed in Cortex in the earlier steps.
Click Next.
Select your newly created policy, and click Next.
Enter a name for your role. Optionally, configure tags. When you are finished, click Create Role.
Search for your new role in the list and copy its name. You will need this in the next steps.
In the upper right corner of AWS, click your name. In the dropdown that appears, copy your AWS account ID. You will need these in the next steps.
Note that if you use multiple AWS accounts, they will share a common rotatable externalId.
Account ID: Enter the AWS account ID you obtained in the previous steps.
IAM role: Enter the role name you obtained in the previous steps.
Click Save.
Step 5: Select AWS resource types
In your AWS integration settings page in Cortex, Cortex will pull all the types you included in the IAM policy into the Cloud Control types dropdown.
If any resource types do not appear in the list, ensure that cloudformation:ListTypes, cloudformation:ListResources, and cloudformation:GetResource are added to the IAM policy so Cortex can pull the list of all available types from AWS.
To select your cloud control types:
In the Cloud control types field, select the types you want Cortex to discover.
If automatic import is enabled, then these types will automatically be imported into Cortex.
If you later need to remove any auto-imported cloud control types, see the FAQ below.
Click Save cloud control types.
If the type you're looking to import is in the list below, please reach out to [email protected] to submit a feature request.
The following Cloud Control types are not currently supported:
How to connect Cortex entities to AWS
For AWS, Cortex replaces non-alphanumeric characters in entity names with a space. For example, resource_1 would become resource 1.
For the Cortex tag, Cortex replaces non-alphanumeric characters with - and lowercases the letters. If multiple special characters appear together in a tag, Cortex replaces the group of characters with only one -. For example, mY_e%ntity#$_tag would become my-e-ntity-tag.
Cortex automatically discovers dependencies between your services and resources by scanning for resources with specific AWS tags. By default, a service will have dependencies on any Cortex resource that has a corresponding AWS resource with AWS tag key = "service" and tag value = the service's Cortex tag.
Customize AWS tag names
In Cortex under the AWS integration page, you can customize the tag key names. Expand the Dependencies sync from AWS section, then select tags from the dropdown menu. Note that an AND operator is used when you select multiple tags; the resource will need to have all specified tags in order to be recognized by Cortex.
If you do not specify tag names, Cortex will use "service" as the key name.
AWS dependency sync
Cortex syncs AWS tags daily at 8 a.m. UTC. To manually refresh the tags, navigate to the relationship graph in your workspace, click the menu in the upper right corner, then click Sync dependencies.
Sync dependencies in the relationship graph.
Use key/value pairs in the entity descriptor for discovery
You can also use explicit tag key/value pairs in the x-cortex-dependency block for AWS dependency discovery. Instead of making a service depend on a resource based on service tags, Cortex will make a service depend on a resource if any of the resource's AWS tags match the explicitly defined key/value pairs in the service's x-cortex-dependency block. For example, the service below will have dependencies on any AWS resource with tag (key = aws:cloudformation:my-key-1, value = arn:aws:cloudformation:my-region:my-value-1) or tag (key = aws:cloudformation:my-key-2, value = arn:aws:cloudformation:my-region:my-value-2).
Cortex can automatically discover ownership for your AWS resources. To enable this, make sure that your AWS resources have a tag matching the x-cortex-tag of the corresponding Cortex team and enable the “Sync ownership from AWS” toggle in the Settings page. By default, we look for the owner tag. You can also customize the tag key name.
Cortex syncs ownership from AWS every day at 6 am UTC.
Editing the entity descriptor
We recommend automatically importing your AWS entities for the fastest and most efficient experience connecting your data. If you need to manually edit entity descriptors, see the information below.
You can associate a Cortex entity with one or more AWS entities. For certain AWS resource types, Cortex will display those AWS entities' metadata on the Cortex entity page.
Multiple ECS services on a single entity
You can associate a Cortex entity with multiple ECS services.
If you are using the Cloud Control resource types, use the format below:
If you are not using Cloud Control types or if you imported your entity prior to Cortex supporting Cloud Control types, you can use the format shown below:
The values for clusterArn and serviceArn are defined in ECS.
Discovery audit
Cortex will pull recent changes from your AWS environment into the discovered entities list. Here, you can find new entities in AWS that have not been imported into the catalog - these will have the tag New AWS Resource - as well as entities in the catalog that no longer exist in AWS - these will have the tag AWS Resource Not Detected.
Using the AWS integration
Searching AWS entities in Cortex
The following keys are supported when searching for your AWS entities in Cortex under Catalogs > All Entities:
aws-account-id - Account ID number
aws-account-name - Account alias
aws-region - AWS region of the resource
aws-type - AWS type of the resource
aws-name - AWS name of the resource
aws-identifier - The primary identifier of a resource
aws-secondary-identifier - The secondary identifier of a resouce
Example search queries
aws-type:"AWS::EC2" AND aws-region:"us-west": Search for entities of category EC2 in the any of us-west regions
aws-account-id: "234512324": Search for all entities from the account 234512324
aws-name:"aws-identifier-of-resource" AND aws-account-name:"test-account": Search for entity with identifier aws-identifier-of-resource in the account with alias test-account
Scorecards and CQL
With the AWS integration, you can create Scorecard rules and write CQL queries based on AWS resources.
If I have auto-import enabled, how can I remove cloud control types that I no longer want to be imported?
If you want to remove any of the cloud control types after importing them: Disable the automatic import setting, remove the cloud control types from your AWS integration settings, then enable auto-archival. This will cause the removed cloud control types to be archived during the next sync.
Why am I seeing the AWS account ID instead of the AWS account alias?
We've recently added support for pulling in the AWS account alias. The required permission is iam:ListAccountAliases (see the AWS documentation here). Once this permission is added, the we will persist the account alias everywhere instead of the ID.
The following options are available to get assistance from the Cortex Customer Engineering team:
Email: [email protected], or open a support ticket in the in app Resource Center
Slack: Users with a connected Slack channel will have a workflow added to their account. From here, you can either @CortexTechnicalSupport or add a :ticket: reaction to a question in Slack, and the team will respond directly.
Don’t have a Slack channel? Talk with your Customer Success Manager.
After you create and save a Scorecard, Cortex automatically evaluates the entities that the Scorecard applies to. How often the Scorecard is evaluated depends on the evaluation window you set when configuring the basic fields of the Scorecard.
Scorecard evaluations are also automatically initiated after Scorecard definition changes are processed via GitOps or other means.
When processing a Scorecard, the individual entity evaluations are spread out over the evaluation window you configured. The evaluation will finish before the next evaluation time is reached. Also note that CQL filters require their own independent evaluation, which can increase the time required to process the evaluation.
Manually trigger an evaluation
To manually trigger a Scorecard evaluation in the Cortex UI:
Navigate to the Scorecard's page in Cortex.
In the details panel on the right side of the page, click Evaluate now.\
You can also kick off a .
Cancel an evaluation
If a Scorecard is in the process of being evaluated, you can cancel it:
Navigate to the Scorecard's page in Cortex.
Click Cancel at the top of the page.\
Review a Scorecard
Reviewing with Cortex MCP
Use Cortex MCP to quickly gain insights into the performance of your Scorecard. Ask questions in natural language, such as: What is going on with my DORA Metrics Scorecard? or What steps can I take to improve my Eng Intelligence Scorecard scores?
Example MCP Scorecard assessment
First, ask a question about a Scorecard. The MCP will display which Cortex APIs are being used to find an answer:
Next, it will provide context to help you improve your scores:
For this example, after listing out the priorities, it also gave us a list of quick wins and a suggestion for a systematic approach:
From there, take action to remediate the issues and start meeting your defined standards.
When you navigate to a Scorecard's page in Cortex, see high-level information, including the median levels achieved per entity, percent of entities at the highest level, and percent of entities that haven't achieved a level. In the side panel, see basic information, including the total number of services being evaluated, scheduled rules, and the next evaluation time.
When reviewing scores, identify where teams or entities have the most friction. Can you automate any processes via Cortex Workflows to improve efficiency?
Share the Scorecard
Need to show progress to leadership? Click Share in the upper right corner. This copies a link to your clipboard, which you can share with anyone who has access to view this Scorecard in your workspace.
Scorecard tabs
On the Scorecard page, click through each of the tabs to learn more about the Scorecard:
Scores
Under Scores, view each entity that is being scored via this Scorecard, the entity's current overall level, and its points or number of rules passed per level.
Point-based Scorecards will display progress based on points, while level-based Scorecards will display the number of passing rules.
For example, in the screen shot above, the first two entities achieved 50 points out of 50 possible points within the Bronze level of the Scorecard. They also each achieved 3 out of 3 possible points under the Silver level.
View more about each entity
Click an entity to open a side panel with more information:
Next to the entity name: A link to its entity details page
At the top of the panel: The entity's current level, score, rank, percentile, and an overview of its rule progress
Under the Rules tab: A list of failing rules, passing rules, and rules not evaluated yet
Filter and sort the scores list
In the upper right corner of the list, click Filter to narrow the scope of the list. You can filter by domain, failing rules, groups, levels, owners, passing rules, and teams.
Click Level to select a different method to sort by, and choose whether to sort ascending or descending.
Overview
Under Overview, see which entity is the highest ranking, which entity is most at-risk, which rule is the most at-risk, the most improved entity, the entity with the worst drop, and the most-moved rule.
Under those metrics, see a graph displaying the progress of all rules. Click All rules above the graph to filter it by specific rules.
By default, the Trends and changes blocks show data from the last month. Click Last month to select a different timeframe.
Rules
Under Rules, view all of the Scorecard's rules, per level. Expand a rule to see its CQL expression:
Note that if you did not set a name for a rule when you created it, it will display here as a CQL expression.
Under Exemptions, view a list of all rule exemptions that have been requested.
Each request includes its current status, the rule, an expiration date, the reason for the request, and the user who requested it.
How exemptions affect scores
When a rule is exempted, entities are not marked as passing or failing — the rule simply does not apply to those entities.
Approving or denying exemptions
You must have the the Configure Scorecard Exemptions permission to approve or deny exemptions.
To approve an exemption, click the checkmark icon. To deny an exemption, click the X icon:
Initiatives
Under Initiatives, see all Initiatives associated with the Scorecard.
Take action on a Scorecard
A failed Scorecard rule gives teams actionable goals to make incremental improvements. Teams can focus on addressing the highest-impact failures first, track progress over time, and celebrate measurable wins, which reinforces a culture of improvement.
To remediate failed rules in a Scorecard:
Identify the failing rules
View the Scores tab on a Scorecard page to view a list of failing rules per entity. You can group by level to understand which entities have reached each level of the Scorecard.
In this example, the group of entities has met the Bronze level, but they are failing rules for Silver and Gold:
Understand the cause
While viewing scores, click into an entity to open a side panel with more information about why rules are failing.
When , add a failure message to give clear steps on how you can remediate the rule if it fails.
When linking to a Cortex workflow that can be run to remediate a failing rule, Cortex will automatically pass in the entity context to the entity selector (if applicable) on the workflow, so it will be selected by default. You can also set this up manually by appending either the Cortex entity tag or entity ID to the workflow URL from a Scorecard or plugin (e.g. ).
if needed: In some cases, a rule may not apply to an entity. You can request to exempt an entity from the rule.
Track and prioritize issues
Use the to see a prioritized to-do list of failing rules across your owned entities and Scorecards. This helps you focus on addressing the most impactful issues first.
Remediate the issues
Address the underlying issue for each failed rule. This could involve adding missing documentation, configuring a monitoring integration, or any other action required to meet the rule's criteria.
In the example screen shot above, the rule failed because PagerDuty is not configured for the entity. You can follow the to ensure that a PagerDuty service, schedule, or escalation policy is configured in the entity's descriptor YAML.
Re-evaluate
The Scorecard will automatically based on its schedule (or you can manually trigger an evaluation), allowing you to see the progress made and any remaining failing rules.\
Scalable remediation
When reviewing your Scorecard evaluations, you may notice trends — some teams struggling in specific areas, or some entities often not meeting standards.
In addition to remediating individual rules, you may want to think about how you can improve larger processes to drive excellence in a scalable way across your organization.
Use Workflows
Look for frequent challenging areas across teams. For example, is a team consistently failing to add runbooks to new services? Are there any failing rules relating to onboarding processes? When a standard is frequently being missed, it indicates an opportunity to automate that process with a Cortex Workflow.
You can use Workflows to streamline a set of repeatable steps, reducing human error and speeding efficiency for your teams.
While viewing a group of entities that are failing rules, you can also look at organizational ways to support your teams or adjust processes.
Team-specific patterns
Are all of the failing entities owned by a newer team?
Ensure that the newer team members are not feeling overwhelmed and have completed any necessary training.
Ensure that the team understands their scope and priorities.
Use dashboards and metrics visualizations to identify which parts of the software development lifecycle could be improved per team.
Does one team own more entities than other teams?
Ensure the workload is spread fairly across your teams.
If one teams owns more due to tribal knowledge, it is a signal to ensure team members are documenting their knowledge. It could also help you identify areas to conduct training sessions.
Are some teams or services successful across several areas?
When viewing teams that are successful or entities that meet all of their standards, find ways to recognize these achievements publicly. Public recognition reinforces good practices and motivates your team.
Service lifecycle patterns
Do older, legacy services have low scores, while newer ones align with standards?
The recommended location for Scorecards is in their own repository, separate from catalog entities, at the repository's root directory within .cortex/scorecards. Note that it is not recommended to put Scorecard definitions in a service repository as Scorecards are not meant to be 1:1 with catalog entitites.
For example, a simple repository might have the following structure:
Any file found within the .cortex/scorecards directory will be automatically picked up and parsed as a Scorecard.
Convert an existing Scorecard to code
You may have Scorecards in Cortex that were created via the UI before you started working via GitOps. To convert an existing Scorecard into code:
Navigate to the Scorecard's details page in Cortex.
Click the vertical ellipsis (⋮) at the top of the page, then click Export Scorecard YAML.\
Add the Scorecard's YAML file to your Git repository.
When GitOps for Scorecard editing is enabled and your Scorecard has been converted to a YAML file in your Git repository, you will no longer be able to edit it via the Cortex UI.
Example Scorecard YAML file
The dora-metrics-scorecard.yaml descriptor file might look something like this:
Scorecard YAML reference
Scorecard objects
name
description
name
The human-readable name of the Scorecard
tag
A unique slug for the Scorecard consisting of only alphanumeric characters and dashes
description
A human-readable description of the Scorecard
draft
Notifications
name
description
enabled
Whether or not to include the Scorecard in notifications
scoreDropNotificationsEnabled
Whether to notify about entities' scores that dropped after each evaluation of this Scorecard
Exemptions
name
description
enabled
Whether or not rule exemptions are enabled for Scorecard
autoApprove
Whether or not rule exemptions are auto approved for Scorecard
userSpecificNotifications
Whether user-specific rule exemption notifications are enabled for Scorecard
Ladder
name
description
levels
The levels of the ladder
Level
name
description
name
The human-readable name of the level
rank
The rank of the Level within the ladder. Higher rank is better.
description
A human-readable description of the level
color
Rules
name
description
title
The human-readable name of the Rule
expression
The CQL expression to evaluate; must evaluate to a boolean
identifier
Identifier of the rule, unique within Scorecard scope. Can be configured to a custom value of your choice. If omitted, we will automatically generate a value.
description
Filter
Note: One of types, groups, or query must be present for it to be considered a valid filter.
name
description
kind
The kind of filter to create. Currently only supports "GENERIC"
types
Types filter (to include / exclude specific types)
groups
Groups filter (to include / exclude specific groups)
query
TypesFilter
Note: Only one of include or exclude can be specified at a time.
name
description
include
List of types to include in set of entities
exclude
List of types to exclude in the set of entities
GroupsFilter
name
description
include
List of groups to include in set of entities
exclude
List of groups to exclude in the set of entities
Evaluation
name
description
window
By default, Scorecards are evaluated every 4 hours. That default can be changed under Settings > Scorecards > Default evaluation window. If you would like to evaluate Scorecards less frequently, you can override the evaluation window. This can help if you're encountering problems with rate limits. Note that Scorecards cannot be evaluated more than once per minimum set in Settings > Scorecards > Minimum evaluation window.
Kubernetes is a container orchestration system that automates software deployment, scaling, and management. The Cortex K8s agent is a lightweight agent that collects information from your cluster (Deployments, StatefulSets, Argo Rollouts, and CronJobs) and surfaces it in your Cortex workspace's catalog, Scorecards, and more.
Integrating Kubernetes with Cortex allows you to:
Discover and import services directly from K8s clusters into Cortex, making it easy to keep the catalog in sync with what's actually running in production
Communication out of the cluster to Cortex happens over HTTPS. There is no inbound traffic to the agent.
Install the Cortex k8s agent in your Kubernetes cluster
To connect Cortex to your Kubernetes instance, you’ll need to install the Cortex k8s agent in your Kubernetes cluster. The agent is lightweight and adds negligible impact to your cluster.
Create a Docker image pull secret:
Run the following command, replacing cortex-key with the value of your Cortex API key, to create a secret in your cluster:
Run the following command to install the Helm chart provided by Cortex:
Connecting Cortex entities to Kubernetes
Discovery
By default, Cortex will use the (e.g. my-entity) as the "best guess" for Kubernetes resource. For example, if your Cortex tag is my-entity, then the corresponding resource in Kubernetes should also be my-entity.
If your Kubernetes resource don’t cleanly match the Cortex tag, you can override this in the Cortex entity descriptor.
Methods for mapping Kubernetes resources
See the table below for the methods of mapping resources to entities:
Method
Use case
Action
See the tabs below to learn how to use each option:
Annotation
You can link your Kubernetes deployment to a Cortex entity by to your k8s deployment metadata. By default, Cortex maps Kubernetes deployments with a cortex.io/tag annotation to Cortex entities with the same tag.
Use cortex.io/tag as the key and use the value of x-cortex-tag in the Cortex entity's cortex.yaml as the value.
For example, if the cortex.yaml file is:
Import entities from Kubernetes
See the for instructions on manually importing entities.
Using the Kubernetes integration
View Kubernetes data on entity pages
Kubernetes deployment data will be available in the Kubernetes block on the for entities imported from Kubernetes or linked to a k8s resource.
In the entity's sidebar, click Environments to see Kubernetes deployments, clusters, active replicas, and pending deployments, as well as:
Replicas: Number of available, ready, and desired replicas.
Containers: Resource containers, including requested memory, memory limit, and CPU data. Also includes the full container definition.
Scorecards and CQL
With the Kubernetes integration, you can create Scorecard rules and write CQL queries based on Kubernetes resources. For an example, see Cortex's prebuilt template.
See more rule examples in the in Cortex.
Cluster information
Data about k8s clusters associated with a given entity.
Definition:k8s.clusters()
Examples
You can use the k8s.clusters() expression in the Query Builder to find all clusters that start with "dev":
Deployment labels
Checks deployment metadata.
Definition:k8s.metadata()
Examples
You can use this expression in a production readiness Scorecard to check ownership:
This rule checks an entity's metadata labels for the ownership annotation and will pass if "ownership_team" is defined.
K8s resource is set for entity
Checks whether a k8s resource of any type is associated with an entity.
Definition:k8s != null
Example
For a Scorecard focused on automation or development maturity, you can set a rule to make sure a k8s resource is mapped:
Kubernetes spec YAML
The periodically sends the raw spec definitions for all entities. The spec JSON is equivalent to the root spec field of the entity descriptor (deployments, StatefulSet, etc.) and fully conforms to that format.
You can find the official documentation for these resource objects in the .
You can use this list of JSON specs combined with jq or to write complex assertions such as "all resources must have specific annotations set" or "all containers should have a CPU resource limit defined."
The list of JSON specs can also be filtered to only ones in a specific cluster by specifying the cluster name: k8s.spec("prod")
Replica information
Number of replicas available, current, desired, ready, unavailable, or updated.
Definition:k8s.replicas()
Example
You can use this expression in a development maturity Scorecard to make sure an entity has at least two available instances:
Background sync
The Cortex k8s agent is a cron job that runs every 5 minutes by default.
FAQs and troubleshooting
When I try to import entities, I don't see all the supported workload types (deployments, ArgoCD rollout, StatefulSet, CronJob)
Make sure that the types you expected to see are in the cluster you are attempting to import.
Missing namespaces from Kubernetes discovery
If you're using to import entities into Cortex but don't see all expected namespaces during the import process, make sure app.namespace is commented out in values.yaml:
If app.namespace is defined the Cortex k8s agent will only be able to discover services from that namespace. This behavior can be confirmed with a backend log similar to:
Once app.namespace is commented out, restart your pods. You will then be able to see all expected namespaces when importing new services.
Helm chart and deprecated Kubernetes Docker registry
If your Cortex agent in Kubernetes clusters is blocked due to deprecation of Docker registry after an upgrade, you can make these direct edits using the same credentials:
Access the image from ghcr.io instead of docker.pkg.github.com.
Update the registry secret, setting the server to https://ghcr.io.
If you are unable to make these changes, please reach out to [email protected] and request a new Helm chart with this change already reflected.
Failing ArgoCD rollouts error in the k8s agent
When running the self-hosted Kubernetes agent successfully, users may see failing ArgoCD rollouts errors while not using this tool.
Cortex logs this exception for verbosity - this error is harmless if not using ArgoCD tool.
Can I deploy on prem if I don’t use Kubernetes?
Yes - the Cortex Helm chart deploys two Cortex-specific pods from images for the frontend and backend, as well as a data store. You can use these images to run Docker containers on other platforms, such as ECS.
Still need help?
The following options are available to get assistance from the Cortex Customer Engineering team:
Email: , or open a support ticket in the in app Resource Center
Slack: Users with a connected Slack channel will have a workflow added to their account. From here, you can either @CortexTechnicalSupport or add a :ticket: reaction to a question in Slack, and the team will respond directly.
Don’t have a Slack channel? Talk with your Customer Success Manager.
New Relic
New Relic is a performance tracking and analytics tool that helps engineers gain visibility into their software. Integrating New Relic with Cortex allows you to:
Discover entities and track ownership
View SLO and monitoring information on entity pages in Cortex
Embed New Relic dashboards on entity pages in Cortex
Create Scorecards to drive alignment on projects involving New Relic metrics
How to configure New Relic with Cortex
Prerequisite
Before getting started:
As a full platform user in New Relic, create a .
New Relic user keys are linked to the account they were created from, so if this account is ever deleted, the integration with Cortex will stop working.
Configure the integration in Cortex
In Cortex, navigate to the :
Click Integrations from the main nav. Search for and select New Relic.
Click Add configuration.
Once you save your configuration, you'll see it listed on the integration's settings page in Cortex. If you’ve set everything up correctly, you’ll see the option to Remove Integration in Settings.
You can also use the Test all configurations button to confirm that the configuration was successful. If your configuration is valid, you’ll see a banner that says “Configuration is valid. If you see issues, please see documentation or reach out to Cortex support.”
Cross-account access
After setting up the integration, you will be redirected to the where you can enable the cross-account access feature. If you have an account that supports subordinate accounts, you can enable this setting to fetch applications and SLOs for all the accounts that are under the configured one.
Configure the integration for multiple New Relic accounts
The New Relic integration has multi-account support. You can add a configuration for each additional by repeating the process above.
Each configuration requires an alias, which Cortex uses to correlate the designated with registrations for various entities. Registrations can also use a default configuration without a listed alias. You can edit aliases and default configurations from the New Relic page in your Cortex settings. Select the edit icon next to a given configuration and toggle Set as default on. If you only have one configuration, it will automatically be set as the default.
How to connect Cortex entities to New Relic
Auto discovery
There are two ways to auto-map New Relic applications and services to Cortex entities:
By default, Cortex will use the (e.g. my-entity) or its name as the "best guess" for New Relic applications. For example, if your Cortex tag is my-entity, then the corresponding application in New Relic should also be my-entity. The name is not case-sensitive.
If your New Relic applications don’t cleanly match the Cortex tag or name, you can override this in the Cortex entity descriptor.
Note: Cortex does not support auto-mapping of SLOs. SLOs have to be defined via the entity YAML or attached to a mapped application or service.
Dependencies
Cortex automatically maps dependencies between your entities by utilizing New Relic's data.
Say you have two applications in NewRelic (Application A and Application B), and in the service map Application A calls Application B. In Cortex you have two Entities (Cortex Entity A and Cortex Entity B), where Cortex Entity A is mapped to New Relic Application A and Cortex Entity B is mapped to New Relic Application B. Cortex will take the mapped relationship from Application A to Application B and create a dependency from Cortex Entity A to Cortex Entity B.
Import entities from New Relic
See the for instructions on importing entities.
Editing the entity descriptor
APM services
New Relic application metrics can be fetched for each entity using application IDs or tags.
Field
Description
Required
Field
Description
Required
Instructions to find your Application ID can be found in the . You can also find the Application ID in the URL in New Relic.
You can also find information on finding and managing tags in the .
OpenTelemetry
services can be associated with the entity only using tags. For this type of service New Relic doesn't generate application ID.
Field
Description
Required
Cortex fetches OpenTelemetry data every 5 minutes, but the data refresh may take longer depending on how much data you have.
Embeds
Cortex can also embed dashboards from New Relic.
Field
Description
Required
Learn more about embedding charts in the page.
SLOs
SLO can be fetched for each entity using New Relic entity GUID for respective SLO or associated service. Detailed instructions how to obtain entity GUID can be found in .
Fetched SLO information can be found in the Operations and Integrations sections of an entity page.
Field
Description
Required
If the alias is not specified, like with the third ID above, Cortex will use the default configuration.
If you use the GUID for a parent service to define the SLOs for a given entity, Cortex will import all SLOs associated with that service.
Using the New Relic integration
View New Relic data on entity pages
When entities are tied to New Relic, SLO and monitoring information appear under the Monitoring section on the overview of the .
More data is available under the Monitoring page in the entity's sidebar:
Throughput
Response time
Error rate
Apdex target
In the SLOs section, you'll be able to see a list of all SLOs tied to that entity, the target and current SLO score, and the period of time the SLO is being calculated for. For example, if the time listed is "7 days ago," then the SLO is looking at the time range starting 7 days ago to now..
The SLO name will display in green when passing and orange when failing.
If you've defined in an entity's YAML, you'll be able to view the graphs from an entity's details page. Open the Dashboard page in the entity's sidebar. All dashboards defined in the descriptor will be embedded on this page.
New Relic dashboards must be defined individually for each entity.
Relationship graphs
detected from New Relic will appear in . You can in the Relationship Graph.
Scorecards and CQL
With the New Relic integration, you can create Scorecard rules and write CQL queries based on New Relic performance metrics.
See more examples in the in Cortex.
Application summary
Fetch high-level for a given New Relic application.
This expression enables you to score entities on reliability metrics:
Apdex score
New Relic application is set
Check if entity has a New Relic application ID set in its entity descriptor.
This can be a good companion to other rules that will fail without a defined application ID, like newrelic.applications().
Definition:newrelic (==/!=) null
Example
Raw NRQL query
Execute an arbitrary NRQL query and capture the .
This expression is not inherently tied to a single entity and requires a custom query to pull the specific data what you need. The raw JSON can be parsed using JQ or language.
Definition:newrelic.rawNrql(query: Text)
Examples
SLOs
SLOs associated with the entity via ID or tags. You can use this data to check whether an entity has SLOs associated with it and if those SLOs are passing.
SLOs
History
OpenTelemetry metrics
OpenTelemetry metrics available in the can be accessed or manipulated for a given entity by combining CQL and native query.
Accessing OpenTelemetry data with CQL and NRQL
In Cortex, you can access OpenTelemetry data by incorporating a raw NRQL query into this CQL expression with the associated .
You can execute raw NRQL query to collect average http.server.requests in a CQL report:
View integration logs
This feature is available to Cortex cloud customers.
On the integration settings page, click the Logs tab to view logs from the last 7 days. Learn more in .
Still need help?
The following options are available to get assistance from the Cortex Customer Engineering team:
Email: , or open a support ticket in the in app Resource Center
Slack: Users with a connected Slack channel will have a workflow added to their account. From here, you can either @CortexTechnicalSupport or add a :ticket: reaction to a question in Slack, and the team will respond directly.
Don’t have a Slack channel? Talk with your Customer Success Manager.
PagerDuty
PagerDuty is an incident response platform that allows developers to manage alerts, schedule rotations, define escalation policies, and more.
Integrating PagerDuty with Cortex allows you to:
Pull in PagerDuty services, on-call schedules, and escalation policies
The on-call user or team will appear in the Current On-call block on an entity's details page.
You can also view on-call information on an entity page in its side panel under Integrations > On-call.
directly from Cortex
Automatically surface the most vital information about entity health and metadata when an incident is triggered by using
The On-Call Assistant automatically notifies users via Slack when an incident is triggered. The notifications include runbooks, links, dependencies, and key information about the affected entity.
View incidents from PagerDuty in an entity's event timeline
View on-call information from PagerDuty in the
Use PagerDuty metrics in to understand key metrics and gain insight into services, incident response, and more.
Create that track progress and drive alignment on projects involving your on-call schedules and alerts
How to configure PagerDuty with Cortex
Prerequisites
Before getting started:
Create a .
When adding the API key, you have the option to set read or write permissions.
Configure the integration in Cortex
In Cortex, navigate to the :
Click Integrations from the main nav. Search for and select PagerDuty.
Click Add configuration.
If you’ve set everything up correctly, you’ll see the option to Remove Integration in settings.
You can also use the Test configuration button to confirm that the configuration was successful. If your configuration is valid, you’ll see a banner that says “Configuration is valid. If you see issues, please see documentation or reach out to Cortex support.”
Enabling the On-call Assistant
At this stage, you can enable the Cortex On-call Assistant, which notifies users via Slack when an incident is triggered in PagerDuty. See the documentation for instructions: .
Note that On-Call Assistant will only work for since these notifications are related to affected services.
How to connect Cortex entities to PagerDuty
Discovery
By default, Cortex will use the (e.g. my-entity) or its name as the "best guess" for PagerDuty services. For example, if your Cortex tag is my-entity, then the corresponding service in PagerDuty should also be my-entity.
If your PagerDuty services don’t cleanly match the Cortex tag or name, you can override this in the Cortex entity descriptor.
Considerations for registering PagerDuty entities
Cortex recommends setting up PagerDuty at the service level by registering service entities with PagerDuty services, rather than configuring team entities with a PagerDuty schedule.
If PagerDuty is set up on a service level, you can see current on-call information listed within a given service's page. If PagerDuty is set up on the team level, you will only be able to view on-call rotation information from a team page.
Other benefits to setting up PagerDuty on a service level include:
Structuring PagerDuty 1-1 with services enables better alert routing and analytics, something that organizations struggle more with when PagerDuty is set up on a team level.
With a service-level setup, it’s easier to enforce all services to have a compliant on-call policy enacted in PagerDuty, especially when making use of Scorecards.
The service-level setup is less reliant on team members tagging incidents with service information because services and incidents are already linked.
View on-call data only
If you want to only view on-call data for entities, and you do not want incidents displayed in Cortex, you can for an entity.
Editing the entity descriptor
For a given entity, you can define the PagerDuty service, schedule, or escalation policy within the entity’s YAML. You can only set up one of these three options per entity.
Each of these has the same field definitions.
Field
Description
Required
Define a PagerDuty service
Find the service ID value in PagerDuty under Configuration > Services. The URL for the service will contain the ID, for example: https://cortexapp.pagerduty.com/services/. You can only configure one service ID per entity.
Define a schedule
Find a schedule ID in PagerDuty under People > On-call schedules. Click the desired schedule to view its ID in the URL, for example: https://cortexapp.pagerduty.com/schedules#. You can only configure one schedule per entity.
Define an escalation policy
Find the escalation policy ID in PagerDuty under People > Escalation Policies. Click the desired policy to view its ID in the URL, for example: https://cortexapp.pagerduty.com/escalation_policies#. You can only configure one escalation policy per entity.
When linking a Cortex entity to a PagerDuty escalation policy, only on-call information will be surfaced in Cortex — incidents will not be shown. This is a useful alternative for teams that want to suppress incident visibility while displaying call schedules.
You can only set up one of the three options above per entity.
Identity mappings
Cortex maps email addresses in your PagerDuty instance to email addresses that belong to team members in Cortex. When is set up, users will be able to see their personal on-call status from the developer homepage.
Using the PagerDuty integration
Entity pages
Once the PagerDuty integration is set up, you’ll be able to view current on-call information in the "on-call" block on an . In the left sidebar of an entity, click On-call & incidents to view on-call information, escalation policy, service, and incidents.
The escalation policy and PagerDuty service details are hyperlinked to the corresponding pages in your PagerDuty instance.
Click Events in an entity's sidebar to view recent events pulled in from PagerDuty.
Engineering homepage
The PagerDuty integration enables Cortex to pull on-call information into the on-call block on the . On-call data from PagerDuty is refreshed every 60 minutes.
Eng Intelligence
Cortex also pulls in metrics from PagerDuty for . This tool will display MTTR, incidents opened, and incidents opened per week.
Retrieve on-call information in Slack
If you have a Slack integration set up, you can also use the /cortex oncall to retrieve current on-call information. This feature works for both services and teams with registered PagerDuty schedules or escalation policies.
Scorecards and CQL
With the PagerDuty integration, you can create Scorecard rules and write CQL queries based on incidents, escalations, and on-call metadata.
See more examples in the in Cortex.
Check if on-call is set
Check if entity has a registered service, schedule, or escalation policy. If the service does not have any registrations in its entity descriptor, Cortex searches for PagerDuty services matching the tag defined in the entity's x-cortex-tag field.
Definition:oncall (==/!=) null
Example
For a Scorecard focused an production readiness, you can use this expression to make sure on-call is defined for entities:
Forbidden contact methods
Number of users in each entity's escalation policy with missing or forbidden contact methods.
Allowed contact methods:
"SMS"
Incident response analysis
Get detailed for each entity:
Mean assignment count
Mean engaged seconds
Incidents
Get incident data for each entity:
Assignee ID
Created at
Number of escalations
Number of escalation tiers in escalation policy.
Definition:oncall.numOfEscalations()
Example
This expression could be used in a Scorecard focused on production readiness or service maturity:
This rule checks that there are at least two tiers in an escalation policy for a given entity, so that if the first on-call does not ack, there is a backup.
On-call metadata
On-call metadata, including type, id, and name.
Definition:oncall.details()
Examples
To find all entities with a schedule-type on-call registration, you can use this expression in the Query builder:
If you're migrating on-call policies, you could use this rule to check for outdated policies. Let's say, for example, all outdated PagerDuty policies start with "Legacy" in their titles.
Trigger an incident
As described above under , a given entity can have a PagerDuty service, schedule, or escalation policy defined. Only entities with a PagerDuty service defined will include the option to trigger an incident directly from Cortex.
Your PagerDuty API key must include the write permission in order to trigger incidents from an entity.
While viewing an entity in Cortex, follow these steps to trigger an incident in PagerDuty:
In Cortex, navigate to an entity. On the left side of an entity details page, click On-call & incidents.
In the upper right side of the entity's "On-call" page, click Trigger incident.
Configure the incident modal:
View integration logs
This feature is available to Cortex cloud customers.
On the integration settings page, click the Logs tab to view logs from the last 7 days. Learn more in .
Background sync
PagerDuty performs the following background jobs:
On-call: On-call information displayed on the developer homepage is refreshed every 60 minutes.
Services and incidents: Services used for automapping and active incidents viewable in the catalog are fetched approximately every 5 minutes, or however long the refresh takes.
Users: User data for identity mapping is synced daily at 10 a.m. UTC.
Still need help?
The following options are available to get assistance from the Cortex Customer Engineering team:
Email: , or open a support ticket in the in app Resource Center
Slack: Users with a connected Slack channel will have a workflow added to their account. From here, you can either @CortexTechnicalSupport or add a :ticket: reaction to a question in Slack, and the team will respond directly.
Don’t have a Slack channel? Talk with your Customer Success Manager.
Create a Scorecard
Use Scorecards to establish best practices, track migration, promote accountability among teams, enforce standardization across entities, or define maturity standards.
This page explains how to create a Scorecard from the Cortex UI. For instructions on creating Scorecards via GitOps, see . You can also work with Scorecards via the .
Learn about reviewing, evaluating, and taking action on failed rules in .
name: DORA Metrics
tag: dora-metrics
description: >-
[DORA metrics](https://www.cortex.io/post/understanding-dora-metrics) are used by DevOps teams to measure their performance.
The 4 key metrics are Lead Time for Changes, Deployment Frequency, Mean Time to Recovery, and Change Failure Rate.
draft: false
notifications:
enabled: true
scoreDropNotificationsEnabled: false
exemptions:
enabled: true
autoApprove: false
userSpecificNotifications: false
ladder:
levels:
- name: Bronze
rank: 1
description: Pretty good
color: "#c38b5f"
- name: Silver
rank: 2
description: Very good
color: "#8c9298"
- name: Gold
rank: 3
description: Excellent
color: "#cda400"
rules:
- title: Ratio of rollbacks to deploys in the last 7 days
expression: >+
(deploys(lookback=duration("P7D"),types=["ROLLBACK"]).length /
deploys(lookback=duration("P7D"),types=["DEPLOY"]).length) > 0.05
identifier: 3c42fa96-b422-30a4-b75a-f8b1cc233408
description: Change Failure Rate
weight: 25
failureMessage: Less than 95% of deployments in the last 7 days were successful
level: Gold
- title: Incident was ack'ed within 5 minutes
expression: oncall.analysis(lookback = duration("P7D")).meanSecondsToFirstAck <= 300
identifier: 8713f2c0-f161-3688-9f99-bcfaab476b63
description: MTTA (Mean time to acknowledge)
weight: 25
failureMessage: Incidents in the last 7 days were not ack'ed
level: Silver
- title: Last commit was within 24 hours
expression: git.lastCommit().freshness = 7
identifier: a16b7eeb-545b-359e-81a7-3946baacdd4b
description: Deployment Frequency
weight: 25
failureMessage: No deployments in the last 7 days
filter:
kind: GENERIC
types:
include:
- service
groups:
include:
- production
evaluation:
window: 4
For example, https://sonarcloud.io if you are on SonarQube Cloud, or https://sonarqube.mycompany.com if your organization has their own instance.
✓
alias
Alias for the configuration in Cortex (only needed if you have opted into multi-account support)
Whether or not the Scorecard is a draft
notifications
Notifications settings for the Scorecard
ladder
The ladder to apply to the rules
rules
A list of rules that are evaluated each time the Scorecard is evaluated
filter
Enables the ability to exclude entities from being evaluated by this Scorecard
evaluation
Enables the ability to change the evaluation window for this Scorecard
The hex color of the badge that is displayed with the level
A human-readable description of the Rule
weight
The number of points this Rule provides when successful
failureMessage
A human-readable message that will be presented when the Rule is failing
level
The name of the level this rule is associated with; can be null even when a ladder is present
filter
Enables the ability to exclude entities from being evaluated for this rule
effectiveFrom
Date when the rule starts being evaluated (e.g. 2024-01-01T00:00:00Z)
A CQL query; only entities matching this query will be evaluated by the Scorecard
Review this section closely to understand areas you can take action on.
Under the Exemptions tab: A list of exempted rules
Under the Progress tab: A graph showing the entity's progress
Use Initiatives to set specific deadlines for higher priority tasks. Cortex will notify owners and team members when deadlines are approaching, helping ensure accountability.
For manual configurations, make sure to add the cloudformation:ListTypes, cloudformation:ListResources, and cloudformation:GetResource permissions so that we can pull the list of types available from AWS.
Configure the New Relic integration form:
Account alias: Enter a name for this account.
Personal key: Enter the user key you generated in New Relic.
Account ID: Enter the ID for the account that the user key was generated with.
Use EU region: Optionally enable this toggle to use the EU region of New Relic.
Click Save.
Cortex also supports mapping New Relic applications to Cortex entities via New Relic tagKeys. By default, a Cortex entity will be mapped to a New Relic application or service with New Relic tag key = "service" and tag value = the service's Cortex tag.
Alias for the configuration in Cortex (only needed if you have opted into multi-account support)
Tag value for the APM service(s)
✓
alias
Alias for the configuration in Cortex (only needed if you have opted into multi-account support)
Tag value for the APM service(s)
✓
alias
Alias for the configuration in Cortex (only needed if you have opted into multi-account support)
Apdex score
Host count
Instance count
Concurrent instance count
Apdex target
Concurrent stance count
Error rate
GUID
Host count
ID
Instance count
Name
Response time
Throughput
Type
If there is not an application ID set in the entity descriptor, a Scorecard rule based on this expression will fail.
Definition:newrelic.applications()
Example
You can use this expression in a Scorecard rule to make sure entities' Apdex score is at least 0.9:
You can use this expression in an onboarding Scorecard to make sure that entities have a New Relic application ID set:
You can use this expression in a Scorecard measuring performance to make sure that the 95th percentile of latency has been less than 500ms in the last 3 weeks for a given entity:
Or you can use this expression in a CQL report to read the timeseries of the process.cpu.usage metric for the last 30 minutes using NRQL and a New Relic service GUID:
ID
Name
Operation
Remaining budget
SLI value
SLO target
Source
Thresholds
SLO datum (timeseries data for the SLI)
Datum
Ts
Named threshold (SLOs thresholds like "warning" or "error" states)
Name
Threshold
Definition:slos
Examples
You can use SLO data from New Relic to evaluate entities in Scorecards. For an onboarding Scorecard, you can make sure that entities have at least 1 SLO defined:
For a project standards Scorecard, you can also use this expression to make sure entities are passing all of their SLOs:
applications
Specifies that the APM service should be found by application ID
✓
applicationID
ID for the application that the service belongs to
✓
tags
Specifies that the APM service should be found by tag
✓
tag
Tag key for the APM service(s)
✓
tags
Specifies that the OpenTelemetry service should be found by tag
✓
tag
Tag key for the APM service(s)
✓
type
Specifies the source of the embed; in this case, should be newrelic
✓
url
URL for the dashboard. It must be publicly accessible, or if you can access the iFrame via VPN, it should be accessible in Cortex while also on the VPN.
✓
id
New Relic entity guid for the SLO or the associated service; if you use the GUID for a parent service, all SLOs associated with it will be imported into Cortex
true
alias
Alias for the configuration in Cortex (only needed if you have opted into multi-account support)
Read: Enables Cortex to read any and all data from PagerDuty
Write: Allows users to trigger incidents from an entity page in Cortex, and enables On-Call Assistant
To use PagerDuty blocks in a Workflow in Cortex, enable the following permissions:
incident.write to create incidents
escalation_policies.write to create escalation policies
schedules.write to create schedules
services.write to create services
teams.write to create teams
Configure the integration:
API key: Enter the API key you created in PagerDuty.
If the Read-only API key option is togged off, Cortex will use assume the provided API key has write permissions.
Click Save.
You will gain the ability to get data from your Cortex catalog into PagerDuty, such as tier/criticality. By tying the service entities in the catalog with those in PagerDuty, you can automate processes and streamline severity protocols.
This rule will pass if an entity has a service, schedule, or escalation policy set.
For a Scorecard focused on service maturity or quality, you can use this expression to check the number of incidents opened in the last month:
Entities will pass this rule if they have fewer than 15 incidents opened in the last month.
You can also use this expression to make sure there aren't incidents that remain open over the last month:
Or you can check for incidents that took a certain amount of time to resolve:
Entities will pass this rule if there were 0 or 1 incidents in the last month that took more than 2 days to resolve.
While making sure an on-call policy set is a rule that would be defined in a Scorecard's first level, a rule focused on escalation tiers would make more sense in a higher level.
Entities with on-call policies that start with "Legacy" will fail, while those with other policy names will pass.
Summary: Enter a title for the incident.
Description: Enter a description of the incident.
Severity: Select a severity level.
At the bottom of the modal, click Trigger incident.
A confirmation screen will appear. In the confirmation, click the link to view the incident in PagerDuty.
id
PagerDuty ID for service, schedule, or escalation policy
jq(newrelic.rawNrql("SELECT percentile(duration) FROM PageView WHERE = '" + newrelic.applications().firstOrNull().name + "' SINCE 3 weeks ago COMPARE WITH 1 week AGO TIMESERIES AUTO"), "[.[].\"percentile.duration\".\"95\"] | add / length") < 500
newrelic.rawNrql("SELECT latest(`process.cpu.usage`) FROM Metric WHERE `entity.guid` = '"+newrelic.applications().getOrNull(0)?.guid+"' SINCE 30 MINUTES AGO TIMESERIES")
slos().length > 0
slos().all((slo) => slo.passing) == true
newrelic.rawNrql("SELECT average(`http.server.requests`) FROM Metric WHERE `entity.guid` = '"+newrelic.applications().getOrNull(0)?.guid+"' SINCE 7 DAYS AGO")
x-cortex-oncall:
pagerduty:
id: ASDF1234
type: SERVICE
Click Integrations from the main nav. Search for and select Kubernetes.
Optionally enter a JQ mapping into the Annotation mapping field.
Click Save mapping.
Note that Cortex looks at the top-level metadata annotations on the Deployment object itself (metadata.annotations), not the pod template annotations (spec.template.metadata.annotations).
If your automapping is not working as expected, make sure the annotation mapping is at the correct default absolute path of .metadata.annotations."cortex.io/tag", or update the annotation mapping in the K8s configuration page to match the exact absolute path of the Cortex tag.
Example
Let's say, for example, your deployment.yaml includes my.service as the cortex.io/tag:
If this deployment should be mapped to a Cortex entity with the tag my-entity, you can enter the following JQ expression to convert all periods in the deployment annotation tag to dashes:
Label-based auto-mapping
You can override Cortex tag discovery and have Cortex discover Kubernetes resources using their metadata labels instead:
Under the K8s auto-mapping customization, specify a list of metadata label keys.
When you are finished, click Save.
Once the list is saved, Cortex will discover all Kubernetes resources with metadata labels with the following criteria:
The resource's spec metadata key contains any of the specified labels
The key values match a Cortex entity tag
Example
For example, let's say you have two Cortex entities (example and entity), and the following Kubernetes JSON blob:
By default, example and entity will have no Kubernetes resource mappings. If the list of metadata labels is set to ["app"], then entity example will be associated with "Sample Kubernetes resource." If the list is set to ["app", "another"], then both example and entity will be associated with the resource.
Editing the entity descriptor
Cortex accepts several k8s resources, which can be on different clusters or of different types: deployments, ArgoCD rollout, StatefulSet, and CronJob.
All of these resource types have the same field definitions:
Field
Description
Required
identifier
Deployments
ArgoCD Rollout
StatefulSet
CronJob
Or any cluster named "prod":
You can also use this expression in the Query Builder to find all k8s deployments with the label "environment":
Or you could refine the query further to find k8s deployments with an "environment" label and that are in production:
.
Definition:k8s.spec()
Examples
You can use this expression to write a wide range of rules. For a best practices Scorecard, you can make sure that resource definitions have set CPU requests:
Or that all resource definitions expose only TCP ports:
By default, Cortex maps Kubernetes deployments with a cortex.io/tag annotation to Cortex entities with the same tag.
Annotation mapping should be at the default absolute path of .metadata.annotations."cortex.io/tag".
To create a Scorecard, you must have the admin or manager role, or you must have a custom role that includes the permission Edit Scorecards.
Scorecards evaluate entities, so before using Scorecards, make sure you have entities in your catalogs.
Make sure you have set up any integrations you want to write rules against.
Step 1: Configure the basic Scorecard fields
When you create a new Scorecard, you can choose from the following options:
Use a Scorecard template
Start from scratch
Option 1: Use a template
Cortex offers the following templates:
Scorecard templates
Onboarding Scorecard
Production Readiness
AI Maturity
Service Maturity
Incident Preparedness
Incident Response Performance
Security Scorecard
SOC 2 Compliance
Vulnerability Management
Secrets Management
Eng Intelligence metrics
DORA Operational Readiness
Velocity Scorecard
Ownership Verification
Entity Verification
Code Quality
JavaScript Best Practices
Minimum Postgres version for Aurora
Minimum version for ElastiCache for Redis
Minimum Lambda runtime versions
Empty Scorecard with Gold/Silver/Bronze levels pre-configured
Expand the tile below to learn how to create a Scorecard from a template.
Create Scorecard from template
To create a Scorecard using a template:
On the Scorecards page in Cortex, click Create Scorecard.
Click Scorecard template.
Click the template you want to use, then at the bottom of the page, click Continue.
You will be redirected to a page that shows the default configuration for your Scorecard, including the integrations used by the Scorecard and the template's levels and rules. You will be able to modify the Scorecard on the next page.
Click Continue at the bottom of the Scorecard default configuration page.
Configure the basic fields for your Scorecard:
Name: Enter a descriptive name for your Scorecard.
Identifier: Enter a unique identifier for your Scorecard.
Select whether to apply this Scorecard to specific entities.
You can choose to include or exclude specific entity types.
Click Advanced options to see additional options for refining entity selection. You can include or exclude groups, and you can include a CQL expression to make your entity type selection.
If you want to use all of the default rules from the template, you can skip ahead to . If you want to add any rules or levels, follow the next steps.
Option 2: Start from scratch
Create Scorecard from scratch
On the Scorecards page in Cortex, click Start from scratch, then at the bottom of the page, click Continue.
Configure the basic fields for your Scorecard:
Name: Enter a descriptive name for your Scorecard.
Identifier: Enter a unique identifier for your Scorecard.
Description: Enter a description for your Scorecard.
Evaluation window: By default, Scorecards are evaluated every 4 hours. If you would like to evaluate Scorecards less frequently, you can override the evaluation window and enter a new number.
If a Scorecard is evaluating such a large number of entities that it cannot complete the evaluation in a 4-hour window without invoking rate limits, then a longer evaluation window is recommended.
Enable notifications: Choose whether to enable notifications.
If notifications are enabled, users who own entities being evaluated by this Scorecard will receive alerts when there are relevant updates on the Scorecard and any corresponding initiatives.
Notify when scores drop: When enabled, you will be notified any time a score drops from the last time the Scorecard was evaluated.
Enable exemptions: Choose whether allow users to request rule exemptions for evaluated entities. If not set, it defaults to enabled.
See for more information.
Enable auto-approval exemptions: If exemptions are allowed, choose whether to enable auto-approval of Scorecard rule exemptions. If not set, it defaults to disabled.
Next to "Apply to specific entities," select whether to apply this Scorecard to specific entities:
Selection type and Entity types: Choose to include or exclude specific entity types. By default, the Scorecard will apply to all entities of the selected type(s).
Click Advanced options to see additional options for refining entity selection. You can include or exclude groups. For example, if you're creating a services-based Scorecard, you might choose to include those that belong in a "tier 1 services" group.
Advanced filtering only works with data that exist within Cortex, like entity groups, owners, and other custom data, but does not extend to third-party integrations.
See the next section for steps on choosing a scoring type and writing rules.
Step 2: Add levels
When you create a Scorecard, there are two options to set up your Scorecard's evaluation:
Level progression
Establish progressive levels as you add rules to make it obvious which set of rules are the highest priority. Levels allow you to set up a gamified system to encourage developers to make progress toward goals and improve entities' performance.
Set your minimum requirements within the lowest level, and add increasingly higher priority rules to subsequent levels.
For an example demonstrating how levels work, see .
Point-based rules
Use points to assign weighted values to each rule you add to a Scorecard.
You can use point-based rules to set minimum requirements while also encouraging teams to add more metadata. For example, you could assign 1 point for adding a single runbook to an entity, and another point for adding additional runbooks:
If you choose to use only point-based rules in your Scorecard, then you do not need to create levels. You can skip to the next section: Step 3: Create a rule.
Add a level
To add a level to a Scorecard:
While creating your Scorecard, in the "Define evaluation rules" section, click Add level.
In the modal, configure your level:
Color: Click the star icon to select a color for this level.
Name: Enter a name that represents this level.
You might choose to go with classic levels names, such as Bronze, Silver, and Gold, or you can choose something more unique to your organization.
Levels are designed to inspire progress on important goals, so consider level names that will motivate your team members.
Description: Enter a description for the level.
Click Add level.
You can add more levels to the Scorecard, or you can move on to the next step and add rules to each level.
Reorder levels
To reorder levels in a Scorecard:
You can reorder levels while creating or editing your Scorecard, if the Scorecard has more than one level. Click the arrows on the right side to reorder them:
Step 3: Create a rule
There are two methods for building a rule:
Using the form builder
Via the CQL editor
The form is the fastest option, as you can choose from pre-configured rules for each integration. The CQL editor is best when writing complex rules or accessing data from multiple sources.
Expand the tiles below for instructions on each option.
Use the form builder
While creating your Scorecard, in the "Define evaluation rules" section, click Add rule.
Level progression scoring type: Click Add rule within a level.
When using the "Level progression" scoring type, we recommend including the most essential rules in the first level so developers know to prioritize them.
Point-based rule scoring type: Enable the toggle next to Point-based rules, then click Add rule:
The rule creation modal defaults to the Form type, where you can choose a pre-configured rule based on configured integrations. \
Configure the basic fields in the form:
Integration: Choose one of your configured integrations to apply this rule to.
Rule: Choose a rule.
Optionally configure the additional fields:
Description: Enter a description for the rule.
Failure message: Add links or instructions to tell users how they can remediate this rule if it's failing.
Click Save rule.
Use the CQL editor
While creating your Scorecard, in the "Define evaluation rules" section, click Add rule.
Level progression scoring type: Click Add rule within a level.
When using the "Level progression" scoring type, we recommend including the most essential rules in the first level so developers know to prioritize them.
Point-based rule scoring type: Enable the toggle next to Point-based rules, then click Add rule:
The rule creation modal defaults to the Form type, where you can choose a pre-configured rule based on configured integrations. To write a CQL expression instead, click CQL:
Configure the basic fields in the form:
CQL expression: Enter your CQL rule. On the right side of the modal, you can use CQL Explorer for help.
Note: If writing an expression that references a Jira issues, Cortex will not append new filter logic to your default JQL query. See for more information.
Optionally configure the additional fields:
Description: Enter a description for the rule.
Failure message: Add links or instructions to tell users how they can remediate this rule if it's failing.
Click Save rule.
You can repeat the steps above to continue adding rules to your Scorecard. You cannot duplicate a rule across levels, since developers will have already completed that task earlier. It is common, however, to have similar rules with different thresholds if you want developers to progress in stages. For example, a base level might require that the P50 latency for API requests is under 5 seconds, while a higher level may required that the same P50 is under 2 seconds.
Step 4: Save the Scorecard
After you have finished adding levels and rules to your Scorecard, you are ready to save it as a draft or publish it.
Choose whether to keep your Scorecard in draft form, visible only to users with permission to configure Scorecards. To keep it in draft form, enable the toggle next to Save as draft.
If you choose to keep your Scorecard in draft status, it will not appear in reports or send notifications.
If you choose to publish your Scorecard, it will be visible to all users who have the View Scorecards permission. Notifications, if enabled, will be triggered.
Click Create Scorecard.
After you save the Scorecard, it will automatically evaluate all the entities that apply based on the rules you have configured, and you will be redirected to the Scorecard's page in Cortex.
Next steps
After you have established Scorecards, there are different steps you can take to continuously improve:
Evaluate progress and take action: Review the Scorecard via reports or by using Cortex MCP, identify trends, and figure out how to take action on the issues you've identified. Learn more in Review and evaluate Scorecards.
Target goals with Initiatives: If you have failing rules, or if you have rules that are a higher priority, you can start using Initiatives to drive progress across the organization. Initiatives allow you to prioritize specific rules within a Scorecard and set deadlines for team members to accomplish tasks. Learn more below.
Create Initiative from Scorecard
Initiatives allow you to prioritize specific rules and set deadlines, making sure your team members complete higher priority tasks on time. In a level-based Scorecard, you can set an Initiative that asks your team to complete all rules within a level by a certain date.
You can create an Initiative while viewing a Scorecard. Note that the Scorecard must be published - i.e., not in draft mode - in order to create an Initiative for it.
In the upper right corner, click +Create initiative.
Jira is a project management tool that helps developers track and manage bugs and work items.
By integrating Jira with Cortex, you can drive improvements and coordinate issue management across teams. Through the integration, you can create Jira work items directly in Cortex based on an Initiative's action items. The integration also allows you to enhance insights into a number of key values for your entities:
Customer facing incidents
Security tickets
Ongoing projects
How to configure Jira with Cortex
It is possible to configure the integration with a Jira Cloud instance or a self-hosted Jira instance (using either basic auth or OAuth). You can also use Cortex Axon Relay to securely integrate your on-premises data. See the tabs below for instructions on each option.
Jira Cloud
Prerequisites
Before configuring Cortex with Jira Cloud:
Create a . To generate a token, you must have the Browse users and groups permissions in Jira and access to the needed Jira projects.
Configure the integration for multiple Jira accounts
The Jira integration has multi-account support. You can add a configuration for each additional by repeating the process above.
Each configuration requires an alias, which Cortex uses to correlate the designated with registrations for various entities. Registrations can also use a default configuration without a listed alias. You can edit aliases and default configurations from the Jira page in your Cortex settings. Select the edit icon next to a given configuration and toggle Set as default on. If you only have one configuration, it will automatically be set as the default.
Set a default JQL query for your Jira integration
You can set a custom JQL query for your and for . This allows you to filter which Jira work items are surfaced on entity pages or in other places in Cortex where CQL is used.
The default JQL applies to jira.issues() and jira.numOfIssues() but not to jira.rawJql().
Note that if you define additional filter logic for your default JQL query when writing a Scorecard rule, you must add that logic in a filter clause. See for more information.
Set default JQL query at a tenant level
From the in Cortex, you can set a custom JQL query for your Jira integration.
When Cortex queries for Jira work items, the statusCategory is directly grabbed from the .
The default query — statusCategory in ("To Do", "In Progress") — will filter your Jira tickets to display only those with To Do and In Progress statuses, excluding closed tickets. The indeterminate status category will map to In Progress
Fallback logic for default JQL
It is possible to set custom JQL at both the entity and tenant level, but note the fallback logic:
If any JQL is passed into a query, Cortex uses that.
If not, Cortex uses entity-level default JQL.
If not, Cortex uses tenant-wide default JQL.
Adding filter logic to the default JQL query in a Scorecard
The CQL statement will use the default JQL setting in a Scorecard rule only if you do not define additional filter logic. Any filter logic applied to the statement will override the default JQL query.
To work around this: If you need to include additional filter logic on your query in a Scorecard, you can move the filter logic to the filter clause.
For example, if your default JQL query is set to "project = project_a", then you can add jira.issues() to a Scorecard rule to automatically surface only the work items relating to Project A. However, you cannot use jira.issues(some_other_filter_logic) in a Scorecard; Cortex will not append your default JQL to the additional filter logic.
In this example, the workaround would be to add a filter clause:
jira.issues().filter(some_other_filter_logic).
How to connect Cortex entities to Jira labels, components, or projects
Discovery
By default, Cortex will tie Jira tickets to entities by searching for any tickets where the label, component, or project field for the work item includes the . For example, if your Cortex tag is “my-entity,” then the corresponding tickets in Jira should have “my-entity” as a label, component, or project.
If your Jira label/component/project doesn't cleanly match the Cortex tag, you can override this in the Cortex .
Without an override, a ticket's label, component, or project must exactly match the Cortex tag in the descriptor.
Connecting via YAML or the Cortex UI
Connect Jira entities via the Cortex UI
Navigate to an in Cortex.
In the upper right corner, click Configure entity.\
Identity mappings
Cortex maps Jira accounts to team members defined in the team catalog, so you do not need to define Jira users in a team member's YAML file.
You can confirm that users' Jira accounts are connected from the .
Using the Jira integration
Entity pages
Once the integration is established, you'll be able to pull in data about the work items in any linked Jira instances for a given entity:
Number of issues: Unresolved issues associated with an entity that have the JQL status "in progress" or "to do"
Number of issues from JQL query: Issues associated with an entity that match an arbitrary JQL query
Cortex will tie Jira tickets directly to entities within the catalog. Click Issue tracking in the entity's sidebar to see associated Jira tickets.
From this tab you can find a list of all issues with a label that matches the Cortex tag.
Key: The issue key (or "ticket number") for a Jira work item.
Issue summary: Title of the Jira work item and the user designated as the issue reporter.
Assignee: User designated as the work item assignee.
This list will also be available from a team's homepage when the team's Cortex tag matches a label, component, or project in Jira.
Initiatives
Initiatives allow you to set deadlines for specific rules or a set of rules in a given Scorecard and send notifications to users about upcoming due dates.
From the Issues tab of an Initiative, you can automatically create a Jira ticket from a failing rule.
Read about creating Jira issues from Initiatives in the documentation: .
Dev homepage
The Jira integration enables Cortex to pull information about issues into the . You can find open work items assigned to you under the . The work items that display will depend both on the Jira instances you've connected and the JQL query defined in Settings.
Work items are refreshed every 5 minutes. You can use the Refresh work items button to manually refresh issues at any point.
Scorecards and CQL
With the Jira integration, you can create Scorecard rules and write CQL queries based on Jira work items.
See more examples in the in Cortex.
Issues
Number of unresolved issues associated with the entity, where unresolved is defined as the JQL status = "Open" OR status = "To Do".
Definition:jira.numOfIssues()
Example
For a Scorecard measuring entity maturity, you can use this expression to make sure entities have fewer than 3 Jira issues:
Issues from JQL query
Number of issues associated with the entity based on arbitrary JQL query.
Definition:jira.numOfIssues(jqlQuery: Text | Null)
Example
For a more specific rule in an entity maturity Scorecard, you can use this expression with a JQL query to make sure entities have no more than 3 open customer-facing tickets.
View integration logs
This feature is available to Cortex cloud customers.
On the integration settings page, click the Logs tab to view logs from the last 7 days. Learn more in .
Background sync
The runs a background job every 5 minutes to refresh the Issues tab.
FAQs and troubleshooting
I've added a Jira integration, but I'm not sure what JQL is being generated to query Jira.
When running Scorecard rules, Cortex appends AND (component = cortex-tag OR labels = cortex-tag OR project = cortex-tag) to the , where cortex-tag is the .
My Scorecard rules are failing, even though there are tickets in my Jira instance.
Make sure that the ticket has a label, component, or project that matches exactly with the Cortex tag or the list defined in your entity descriptor.
I received "Configuration error: Integration error for Jira: Unexpected HTTP response 0".
When using Jira Cloud, you'll need to create a Jira API token and add it on in Jira Settings in Cortex. The email address in Settings must be the same as the user that the token is associated with. Cortex also expects only the subdomain of your Jira instance, not the entire URL.
I received "Configuration error: Jira: Unexpected HTTP response 403: Forbidden".
Make sure that the entity name in Cortex matches the label, component, or project name in Jira.
Make sure the subdomain and base URL correspond with the Jira instance you're trying to connect.
Verify that the Jira token you added is still valid. You can run the following to confirm:
I configured the integration, but I am not seeing Work Items populate.
The background job fetches work items every 5 minutes. However, a fresh integration configuration may result in longer waiting times, as it also fetches historical data.
Still need help?
The following options are available to get assistance from the Cortex Customer Engineering team:
Email: , or open a support ticket in the in app Resource Center
Slack: Users with a connected Slack channel will have a workflow added to their account. From here, you can either @CortexTechnicalSupport or add a :ticket: reaction to a question in Slack, and the team will respond directly.
Don’t have a Slack channel? Talk with your Customer Success Manager.
Slack
Slack is a messaging and collaboration platform that makes it easy to communicate with your team and work together efficiently on projects.
Integrating Cortex with Slack allows you to:
Quickly find the relevant Slack channel to communicate with the right team, allowing for easier collaboration on projects and faster communication during an incident
Receive directly in Slack for Scorecard changes, upcoming Initiatives, weekly summaries of entity performance, and more
If you use the , receive notifications when an incident is triggered
Interact with the to query entity metadata and Scorecard scores
Create that enforce standards such as having Slack channels set for projects
How to configure Slack with Cortex
Prerequisites
To configure this integration:
Your Cortex user must have the Configure integrations permission
You must be an administrator in your Slack account
The Slack account must not be linked to another Cortex tenant
If you're using a self-managed Cortex instance, you'll need to follow a manual configuration process to use Cortex's app for Slack. Follow the .
Step 1: Configure the integration in Cortex
In Cortex, navigate to the :
Click Integrations from the main nav. Search for and select Slack.
Click Add configuration.
After signing in to Slack and granting permission for Cortex to access the Slack workspace, you are redirected to the Slack integration settings page in Cortex. In the upper right corner of the page, click Test configuration to ensure Slack was configured properly.
Step 2: Configure Slack app settings
On the , you can configure additional options:
Require Cortex account to use Cortex's Slack app: Enable this setting if you want Cortex's Slack app to only work for users who have Cortex accounts.
Slack notifications: You can configure notifications to be sent via Slack for your organization. Click Notification settings to go directly to the notification configuration page for your workspace.
Learn more about notifications below, under .
Using the Slack integration
Viewing Slack information across Cortex
Slack channels associated with teams or entities will appear in several places across Cortex:
: Slack channels will appear at the top of an entity's overview page in a Slack channels block, and in the "Owners" page in the entity's sidebar. You can click any channel name to go directly to that channel in Slack.\
You can write CQL queries and Scorecard rules based on Slack channels. Learn more under .
Managing Slack notifications
After configuring the Slack integration, you can choose whether to allow Slack notifications for your workspace.
In Cortex under Settings > Notifications, an admin or a user with the Configure workspace notification settings permission can enable or disable the option to receive notifications via Slack for each type of notification. Users can also adjust their to control which notifications they receive via Slack.
Team, user, and entity Slack notifications
Notifications are . DMs and channel notifications are sent from the .
User-based notifications are sent to users via a Slack DM.
Team-based notifications are sent to the Slack channel associated with a team.
Entity-based notifications are sent to the Slack channel associated with an entity.
Note that notifications can be sent to private Slack channels, but the Cortex Slack Bot must be a member of the channel in order for the notification to be delivered to the channel.
Learn more about notifications in the .
Using the Cortex Slack bot
After configuring the Slack integration, you can use commands to interact with the Cortex Bot in your Slack workspace. The Cortex Bot also powers notifications that are sent via Slack.
The Cortex Bot is a Slack app called "Cortex."
Cortex Bot notifications
The Cortex Bot sends you notifications based on (and based on your ).
In addition, the Cortex bot will send user-based and team-based weekly reports. The weekly report for users summarizes how their entities are tracking against Scorecards and Initiatives; the report for teams delivers the same summary for entities owned by that team.
Add the Cortex Slack Bot to a private channel
To ensure you receive notifications to a private channel, make sure you have added it to that channel:
Open the Slack channel where you want to add the bot.
Type and enter @Cortex.
Slack will prompt you to take an action. Click Add them.
Cortex Bot Commands
Using the below commands in Slack, you can quickly query entity metadata and Scorecard scores. The <tag> refers to the .
Using AI assistant in Slack
The AI assistant is in public beta. Check out the here for more details. Please contact your Cortex Customer Success Manager if you are interested in participating in the public beta.
As with all Large Language Models (LLM), the AI Assistant may not provide accurate responses. Please reach out to Cortex Customer Engineering if you encounter any issues.
The Cortex AI assistant is a conversational interface that helps you navigate Cortex. You can ask the AI assistant questions such as "Which entities do I own?"
Use it with Slack in the following ways:
In a public channel: Tag Cortex (type @Cortex) and ask a question.
In a DM: Message the Cortex app directly and ask a question.
View integration logs
This feature is available to Cortex cloud customers.
On the integration settings page, click the Logs tab to view logs from the last 7 days. Learn more in .
How to connect Cortex entities to Slack channels
In order to use this integration's functionality, your Slack channels need to be associated with entities in Cortex. You can connect Slack channels to teams and other entities in an when following a approach, or you can connect them in the Cortex UI.
Without configuring the Slack integration, you can also add a Slack channel as an on an entity.
Editing the entity descriptor
You can define Slack channels by name or ID, and enable or disable to the channel, in an entity descriptor for any entity type. Defining a Slack channel will enable direct access to the channel from the entity's page in Cortex.
When to define by name vs. channel ID
When you , it is more easily recognizable to users when viewing the entity's YAML. However, if a Slack channel's name is likely to change, it's better to as it won't break the entity's Slack link in Cortex.
Defining by channel IDs
Identity mappings
Cortex maps email addresses in your organization's Slack workspace to email addresses that belong to team members, so you never need to define email addresses in the entity descriptor.
You can confirm that users' Slack accounts are connected from the tool or from the .
Scorecards and CQL
With the Slack integration, you can create Scorecard rules and write CQL queries based on Slack channels.
See more examples in the in Cortex.
Check if Slack channel is set
Checks if an entity has a registered Slack channel in its entity descriptor.
Definition:slack (==/!=) null
Example
For a Scorecard focused on onboarding entities, you can define a rule to make sure each entity has a registered Slack channel:
Defining a rule to make sure a Slack channel is set is a good way to make sure that users can reach out to entity owners for more information or if an issue arises.
Number of Slack channels
Counts the number of Slack channels registered for a given entity.
Definition:slack.channels().length
Example
Similar to slack != null, you can use this expression to write a rule checking that entities are linked to a Slack channnel:
Total number of members across Slack channel
Counts the total number of members across all registered Slack channels.
Definition:slack.numOfMembers()
Example
You can use this expression in the Query Builder to find entities linked to empty Slack channels:
If an entity is linked to an empty Slack channel, it might indicate a gap in your notification process.
Background sync
Cortex conducts a background sync of Slack identities every day at 10 a.m. UTC.
FAQs and troubleshooting
Can users access information via the Slack Bot if they haven't logged in to our Cortex instance?
Yes, this is possible, depending on the settings you configured for the Slack Bot in your workspace. To allow users to use the Slack Bot without logging in to Cortex, navigate to the in Cortex and disable the toggle next to Require Cortex account to use Cortex's Slack app.
Can I disable some of the notifications I receive in Slack?
You can adjust your , but note that .
Is the Slack integration required to add Slack channels to a team?
No, the Slack integration is not required to add channels to Cortex teams. You can manually add any Slack channels without setting up the Slack integration or for a team’s metadata.
Why isn't my Slack channel showing up after I've added it to an entity's YAML configuration?
Slack channels are cached and refreshed every 4 hours, so newly-added channels may not appear immediately in the UI.
Privacy policy
Cortex retains basic Slack metadata like user IDs for the period necessary to fulfill the purposes outlined in our unless a longer retention period is required or permitted by law, or where the Customer Agreement requires or permits specific retention or deletion periods.
To request to access, transfer, or delete data, you can reach out to the Cortex support team.
Still need help?
The following options are available to get assistance from the Cortex Customer Engineering team:
Email: , or open a support ticket in the in app Resource Center
Slack: Users with a connected Slack channel will have a workflow added to their account. From here, you can either @CortexTechnicalSupport or add a :ticket: reaction to a question in Slack, and the team will respond directly.
Don’t have a Slack channel? Talk with your Customer Success Manager.
kubectl create secret docker-registry cortex-docker-registry-secret \
--docker-server=ghcr.io \
--docker-username={provided by Cortex} \
--docker-password={token provided to you by the Cortex team} \
--docker-email={email address}
INFO 1 --- [ scheduling-1] k8sagent : Looking for stateful sets in namespace
image: ghcr.io/cortexapps/k8s-agent...
Error polling argocd rollouts from Kubernetes API
io.kubernets.client.openapi.ApiException:
[...]
at com.brainera.k8sSDKClient.getArgoRollouts(k8sClient.kt:101) ~[app:/na]
x-cortex-k8s:
deployment:
- identifier: namespace/name
cluster: dev
- identifier: experiment/scratch
cluster: dev
- identifier: default/cortex
cluster: prod
x-cortex-k8s:
argorollout:
- identifier: namespace/name
cluster: dev
x-cortex-k8s:
statefulset:
- identifier: namespace/name
cluster: dev
x-cortex-k8s:
cronjob:
- identifier: namespace/name
cluster: dev
Description: Enter a description for your Scorecard.
Evaluation window: By default, Scorecards are evaluated every 4 hours. If you would like to evaluate Scorecards less frequently, you can override the evaluation window and enter a new number.
If a Scorecard is evaluating such a large number of entities that it cannot complete the evaluation in a 4-hour window without invoking rate limits, then a longer evaluation window is recommended.
Enable notifications: Choose whether to enable notifications.
If notifications are enabled, users who own entities being evaluated by this Scorecard will receive alerts when there are relevant updates on the Scorecard and any corresponding initiatives.
Notify when scores drop: When enabled, you will be notified any time a score drops from the last time the Scorecard was evaluated.
Enable exemptions: Choose whether to enable Scorecard exemptions. If not set, it defaults to true.
Enable auto-approval exemptions: Choose whether to enable auto-approving of Scorecard rule exemptions. If not set, it defaults to false.
Enable user-specific notifications: Add a field to allow your users to notify a specific user to approve a rule exemption request rather than all Admins.
If this field is enabled, Scorecard notifications will also be enabled automatically.
When including a CQL expression, you will have the option to test the query against specified entities to verify that it works as expected.
You can also include a CQL expression to make your entity type selection.
The next fields vary depending on the type of rule you choose. For example, you may need to choose a boolean operation or set a file path.
Rule name: Enter a descriptive name. Names make it easier to understand the outcome of the rule without having to read the CQL expression.
Restrict rule to specific groups: Select groups to include or exclude.
This option can be used when a group of entities should be evaluated by the Scorecard as a whole, but a specific rule in the Scorecard does not apply to that group.
You can use points to signify each rule's importance. Rules worth more points are more critical than those with fewer points.
Schedule evaluation start date: If you want to schedule the evaluation of a rule to start on a specific date, schedule a start date here. When the field is blank, the rule will take effect immediately. If a start date is provided, the rule will take effect at the start of the specified day (UTC).
This is helpful when you want users to be aware of an upcoming rule, but you do not want to evaluate the Scorecard yet based on that rule.
Scheduled rules are visible to all users and will be included in the weekly team and user reports to help with socialization.
Users can choose to when a scheduled rule is added to a Scorecard evaluating an entity they own, and they can receive reminders before a scheduled rule impacting an owned entity goes into effect.
Rule name: Enter a descriptive name. Names make it easier to understand the rule without having to read the CQL expression.
Restrict rule to specific groups: Select groups to include or exclude.
This option can be used when a group of entities should be evaluated by the Scorecard as a whole, but a specific rule in the Scorecard does not apply to that group.
You can use points to signify each rule's importance. Rules worth more points are more critical than those with fewer points.
Schedule evaluation start date: If you want to schedule the evaluation of a rule to start on a specific date, schedule a start date here. When the field is blank, the rule will take effect immediately. If a start date is provided, the rule will take effect at the start of the specified day (UTC).
This is helpful when you want users to be aware of an upcoming rule, but you do not want to evaluate the Scorecard yet based on that rule.
Scheduled rules are visible to all users and will be included in the weekly team and user reports to help with socialization.
Users can choose to when a scheduled rule is added to a Scorecard evaluating an entity they own, and they can receive reminders before a scheduled rule impacting an owned entity goes into effect.
Click Integrations from the main nav. Search for and select Jira.
Click Add configuration. then select Cloud for the integration type.
If you are using a scoped token, select Cloud (scoped token).
In the Jira integration modal, "Jira Cloud" is selected by default in the upper right corner. Configure the integration form:
Account alias: Enter an alias for your account.
Subdomain: Enter the subdomain for your Jira instance.
Click Save.
Jira on-prem (Basic)
Prerequisite
If you're using a self-hosted instance of Jira, you'll need to verify that your Cortex instance is able to reach the Jira instance.
We route our requests through a static IP address. Reach out to support at [email protected] to receive details about our static IP. If you're unable to directly allowlist our static IP, you can route requests through a secondary proxy in your network that has this IP allowlisted and have that proxy route traffic to your Jira instance.
In Cortex, click your avatar in the lower left corner, then click Settings.
Under "Integrations," click Jira.
Click Add configuration.
In the upper right corner of the Jira integration modal, click the dropdown labeled Cloud. Select On-prem (basic auth).
Configure the Jira integration form:
Account alias: Enter an alias for your account.
Host: Enter the URL for your Jira on-premises host.
Click Save.
Jira on-prem (OAuth)
Prerequisites
To integrate Cortex with Jira using OAuth, you must be running a self-hosted Jira instance with Jira server version 8.22 or higher.
If you're using a self-hosted instance of Jira, you'll need to verify that your Cortex instance is able to reach the Jira instance.
We route our requests through a static IP address. Reach out to support at [email protected] to receive details about our static IP. If you're unable to directly allowlist our static IP, you can route requests through a secondary proxy in your network that has this IP allowlisted and have that proxy route traffic to your Jira instance.
Step 1: Create an application link from Jira
In your Jira server, navigate to Settings > Applications > Application Links. Click Create link.
Configure the application link settings:
Application type: Select External.
Direction: Select Incoming.
Click Save.
The application link will have an associated client ID and client secret. Copy these values and store them in a secure location, as you will need them in the next steps.
Step 2: Configure the integration in Cortex
In Cortex, navigate to the :
In Cortex, click your avatar in the lower left corner, then click Settings.
Entering a custom JQL query on the Jira integration settings page allows you to override the default for all entities in your workspace. To map work items with a custom status, you can write a custom JQL query that uses status instead of statusCategory.
Set default JQL query at entity level
You can configure default JQL for entities in their entity YAML. For example:
If none, then no JQL is used for filtering.
Click the Project management tab, then click +Add.\
In the side panel, configure the details:
Jira service type: Choose component, label, or project.
Alias: If you have multiple Jira configurations, select which one this service is associated with.
Name: Enter the name of the service.
At the bottom of the side panel, click Add.
Editing the entity descriptor
If you need to override automatic discovery, you can define x-cortex-issues blocks in your Cortex entity descriptor.
Note: For all of the following, alias is optional, and the default Jira configuration will be used if not provided. You can use Jira labels, components, or projects to match entities.
Each of these blocks has the same field definitions.
Field
Description
Required
By default, Cortex will surface outstanding issues per entity in the catalog with a default query: statusCategory in ("To Do", "In Progress"). If you'd like to override this, you can provide a new default query with:
Priority: The work item's priority level in Jira - Lowest, Low, Medium, High, Highest. This will display with the icon that corresponds to the priority level in your Jira instance.
In the side panel, click Add to Slack. A pop-up window will appear.
In the pop-up window that appears, sign in to your Slack workspace.
After signing in, a permission page will load in the pop-up window.
On the permission page, click Allow.\
Identity mappings: You can map email addresses from your Slack workspace to email addresses of team members in Cortex, making sure the integration works as expected for users. Click Identity mappings to go directly to the Identity mapping configuration page for your workspace.
List information for any entity, combining the behavior of service, team, domain and resource
/cortex help <tag>
Display the full list of commands
/cortex links <tag>
List all
/cortex links [type] <tag>
List all links of a type parameter, such as metrics or openapi
/cortex logs <tag>
List all
/cortex oncall <tag>
Find current on-call info
/cortex owners <tag>
List all owners and their email addresses
/cortex resource <tag>
List resource information, such as owners, on-call, links, and timeline events
/cortex runbooks <tag>
List all
/cortex scores <tag>
List all Scorecard scores
/cortex search <tag>
Query for entities using .
For example:
- Search by tag with key:value
- Use wildcards: foo*, foo:bar*
- Search by group with group:name
/cortex sentry <tag>
List recent Sentry issues
/cortex service <tag>
List service information, such as owners, on-call, links, and timeline events
/cortex team <tag>
List team information, such as owned entities, links, and timeline events
/cortex timeline <tag>
List recent timeline events
We recommend registering Slack channels by ID, as channel names may change.
Field
Description
Required
id
Slack channel ID
✓
notificationsEnabled
Boolean to enable/disable notifications in Slack
✓
Defining by channel names
Field
Description
Required
name
Slack channel name
✓
notificationsEnabled
Boolean to enable/disable notifications in Slack
✓
Connect channels to entities without configuring the Slack integration
You can connect Slack channels to entities without configuring the Slack integration. Note that this method will only provide a link to Slack from the entity; it will not include any features of the Slack integration, such as ownership tracking, notifications, Slack Bot, and the ability to use CQL to query Slack data.
Use Slack's redirect link format, https://slack.com/app_redirect?channel={channel_name}, to add the link to an entity YAML, under the x-cortex-slack block. Make sure to replace channel_name with your Slack channel's name.
List domain information, such as owners, on-call, links, and timeline events
Bitbucket
Bitbucket is a Git-based version control system from Atlassian. You can use Bitbucket to drive insights into repository details in the Catalog and Scorecard rules.
Integrating Bitbucket with Cortex allows you to:
Discover and track ownership of Bitbucket entities
Use Bitbucket metrics in to understand key metrics and gain insight into services, incident response, and more
Create that track progress and drive alignment on projects involving your Bitbucket repositories
Bitbucket data in and in the is available in private beta. Please contact your Cortex Customer Success Manager for access.
How to configure Bitbucket with Cortex
There are multiple options for integrating with Bitbucket:
Cloud: Using a workspace token (recommended), the Cortex Atlassian app, or an app password.
On-prem: Using Basic auth or using OAuth
You can also integrate using Cortex Axon Relay, a relay broker that allows you to securely connect your on-premises Bitbucket data.
See the tabs below for instructions on the method you choose.
Configure Cortex with Bitbucket using a workspace token
Step 1: Generate a workspace token in Bitbucket
In Bitbucket, navigate to Settings > Workspace settings > Access tokens.
Create a workspace-level access token. Include the following scopes:
Once you save your configuration, you'll see it listed on the integration's settings page in Cortex. If you’ve set everything up correctly, you’ll see the option to Remove Integration in Settings.
You can also use the Test all configurations button to confirm that the configuration was successful. If your configuration is valid, you’ll see a banner that says “Configuration is valid. If you see issues, please see documentation or reach out to Cortex support.”
Configure the integration for multiple Bitbucket accounts
The Bitbucket integration has multi-account support. You can add a configuration for each additional by repeating the process above.
Each configuration requires an alias, which Cortex uses to correlate the designated with registrations for various entities. Registrations can also use a default configuration without a listed alias. You can edit aliases and default configurations from the Bitbucket page in your Cortex settings. Select the edit icon next to a given configuration and toggle Set as default on. If you only have one configuration, it will automatically be set as the default.
Cortex supports mapping multiple identities for a single user if you have multiple configurations of Bitbucket. See the documentation for more information.
Limit which Bitbucket projects are used for the integration
If you are a part of multiple projects in Bitbucket but you only want to show repositories for a specific set of projects, you can specify the projects in Cortex:
Navigate to the .
Click the pencil icon in the row containing the Bitbucket configuration you want to edit.\
Under Project names, select which projects you want to include.
Use webhooks for GitOps functionality
To use webhooks for GitOps functionality, you need to set a secret token on the page. This helps Cortex identify that the webhook event is valid. Make sure to enter the same secret when configuring the webhook on Bitbucket Server. \
How to connect Cortex entities to Bitbucket
Import entities from Bitbucket
See the for instructions on importing entities.
Editing the entity descriptor
Set repository details
By specifying the x-cortex-git field in your Cortex entity descriptor, you'll be able to see Git information in the entity page, including the top language, recent commits, and top contributors.
Field
Description
Required
The value for repository should be the workspace/repo as defined in Bitbucket.
Ownership
You can define the following block in your Cortex entity descriptor to add your Bitbucket teams.
Field
Description
Required
Identity mappings
Cortex maps users' email addresses to discovered Bitbucket accounts, so you never need to define email ownership in an entity descriptor.
You can confirm users' Bitbucket accounts are connected from .
Using the Bitbucket integration
View Bitbucket information on entity pages in Cortex
The Bitbucket integration populates the Repository block on an . For cloud configurations, it also populates the Language block. If a Bitbucket team has been defined as the owner for an entity, it will also appear in the Owners block.
In the Recent activity preview, you'll find the recent commits and releases.
Events
On an entity's Events page, you can find all of the commits and releases associated with that entity. Each is hyperlinked to the commit or release page in Bitbucket and includes a timestamp.
CI/CD
To see pipeline runs for Bitbucket, use the to add deploy information. After doing this, from the CI/CD > Deploys page in the entity's sidebar, you will see a history of pipeline runs.
Workflows
If a Workflow applies to a given entity, any actions you can perform are available under the Workflows link in the side panel of an entity.
Repository
You can access more detailed information pulled from Bitbucket in the Repository link in the sidebar. At the top of the repository page, see the repositories associated with that entity. For cloud configurations, you can also see the most-used language in files for that entity. In the Top contributors block, you'll find the three users who have contributed the most code and the number of their contributions.
In the Commits section, you'll find the 10 most recent commits and metadata about each. Below Commits is the Recent releases section, which includes the 5 most recent releases.
Packages
Packages are automatically scraped from your Git repos or they can be submitted via the . The package file must be in the root of your repository — or, if you're using basepath, in the root of the subdirectory — to be scraped by Cortex. You can query an entity's packages in using packages().
To view packages, click Packages in the entity's sidebar.
The following package types are automatically scraped from repositories:
All other files of these types can be added via the .
Engineering homepage
Bitbucket in the homepage is available in private beta. Please contact your Cortex Customer Success Manager for access.
Note: Because of rate limits, Bitbucket ingestion in the homepage is limited to repositories that are mapped to an entity in Cortex.
The Bitbucket integration enables Cortex to pull information about pull requests and work items into the . You can find your open pull requests and any pull requests assigned to you for review.
Pull requests from Bitbucket are refreshed every 5 minutes.
Eng Intelligence
Bitbucket in Eng Intelligence is available in private beta. Please contact your Cortex Customer Success Manager for access.
Note: Because of rate limits, Bitbucket ingestion in Eng Intelligence is limited to repositories that are mapped to an entity in Cortex.
The also uses pull request data from Bitbucket to generate metrics:
Average PR open to close time
Avg time to first review
Avg time to approval
PRs opened
You can read more about how Eng Intelligence tracks metrics for teams and users in the Eng Intelligence walkthrough.
Scorecards and CQL
With the Bitbucket integration, you can create Scorecard rules and write CQL queries based on Bitbucket details.
See more examples in the in Cortex.
Approvals required to merge
The total number of approvals required to merge a Pull Request into the repository, defaulting to 0 if no approvals are defined.
Definition:git.numOfRequiredApprovals(): Number
Example
In a Scorecard, you can write a rule to encourage at least one approval for each Pull Request:
Git repository set
Check if an entity has a registered Git repository.
Definition:git (==/!=) null: Boolean
Example
In a Scorecard, you can write a rule that detects whether an entity has a Git repository set:
Pipeline build success rate
The percentage of build pipelines that complete successfully. This is calculated against builds on the default branch, for commits in the last 30 days. The calculation is # successful builds / (# successful + # failed). Definition:git.percentBuildSuccess(): Number
Example
In a Scorecard, you can write a rule that requires at least 90% of build runs to be successful:
View integration logs
This feature is available to Cortex cloud customers.
On the integration settings page, click the Logs tab to view logs from the last 7 days. Learn more in .
Background sync
Cortex conducts a background sync of Bitbucket identities every day at 10 a.m. UTC. Repositories are refreshed every day at 2 p.m. UTC.
Troubleshooting and FAQ
Rules are failing saying that I don't have file x, but I verified that the file exists.
We always use the default branch for file existence checks. Make sure that the file is present in the default branch.
Still need help?
The following options are available to get assistance from the Cortex Customer Engineering team:
Email: , or open a support ticket in the in app Resource Center
Slack: Users with a connected Slack channel will have a workflow added to their account. From here, you can either @CortexTechnicalSupport or add a :ticket: reaction to a question in Slack, and the team will respond directly.
Don’t have a Slack channel? Talk with your Customer Success Manager.
For example, this field would take cortex-docs from https://cortex-docs.atlassian.net.
Base URL: This field automatically populates atlassian.net.
If you are using a legacy Jira Cloud instance (i.e., you access your Jira instance on jira.com), change the base URL from the dropdown.
Email: Enter the email address associated with the user who generated the token in Jira.
Note: The email address associated with a given Jira token must match the email address of the user associated with that token.
API token: Enter your Jira API token.
Frontend host: Enter the URL for your Jira on-premises frontend host.
Username and Password: Enter your Jira username and password.
Redirect URL: For default configuration, enter the URL of your Cortex instance appended with /oauth/internal/jira. For a non-default configuration, enter the URL of your Cortex instance appended with /oauth/internal/jira/.
Permission: Select write.
Click Add configuration.
In the upper right corner of the Jira integration modal, click the dropdown labeled Cloud. Select On-prem (OAuth).
Configure the Jira integration form:
Account alias: Enter an alias for your account.
Host: Enter the URL for your Jira on-premises host.
Frontend host: Enter the URL for your Jira on-premises frontend host.
Client ID and Client secret: Enter the client ID and secret associated with the application link you created in the previous steps.
Click Save.
You will be redirected to the Jira settings page. Click Install next to your integration name.
A confirmation modal will appear, asking you to allow Cortex access to your Jira account.
The accessing user can be a user persona or a system account. We recommend using a system account to maintain your organization's access in case the user who set up the integration leaves your organization.
name
Label name in Jira
✓
alias
Alias for the configuration in Cortex (only needed if you have opted into multi-account support)
Click Integrations from the main nav. Search for and select Bitbucket.
Click Add Bitbucket configuration.
For the configuration type, select select Atlassian app.
Configure the "Add Bitbucket configuration" form:
Account alias: Enter an alias for the account. Aliases are used to tie service registrations to different configuration accounts.
Click Save.
You will be redirected to the Bitbucket Settings page in Cortex.
Step 3: Connect to Atlassian from Cortex
On the in Cortex, click Atlassian Application.
In the popup that appears, click Grant access to authorize Cortex access to your Atlassian Workspace.
Configure Cortex with Bitbucket using an app password
Bitbucket is deprecating app passwords on June 9, 2026. If you are currently using an app password, we recommend switching to a workspace token or the Atlassian app before that date.
Step 1: Create an app password
Follow Atlassian's documentation to .
Make sure to give the app password the following minimum permissions: Repositories: Admin, Repositories: Read, Pull requests: Read
Step 2: Configure the integration in Cortex
In Cortex, navigate to the .
Click Integrations from the main nav. Search for and select Bitbucket.
Click Add configuration.
Step 3: Set your Bitbucket workspace
On the in Cortex, next to your integration's alias, click Add workspace.
In the "Workspace configuration" modal, enter your Workspace name.
You can find this in Bitbucket under Settings > Workspace settings.
Configure Cortex with Bitbucket using a on-premises basic auth
Bitbucket is deprecating app passwords on June 9, 2026. If you are currently using an app password for basic auth, we recommend switching to an alternative authentication method before that date.
Step 1: Create an app password
Follow Atlassian's documentation to .
Make sure to give the app password the following minimum permissions: Repositories: Admin, Repositories: Read, Pull requests: Read
Step 2: Configure the integration in Cortex
In Cortex, navigate to the .
Click Integrations from the main nav. Search for and select Bitbucket.
Click Add configuration.
Note: When using an on-premises configuration of Bitbucket, the language does not populate on .
Configure Cortex with Bitbucket on-premises using OAuth
Prerequisites
To configure this integration with on-prem OAuth, you must be running a self-hosted Bitbucket instance with Bitbucket Server or Data Center version 7.20 or higher.
Step 1: Set up an application link in Bitbucket
In your Bitbucket server, navigate to Settings > System > Application Links > Create Link.
Configure the application link:
For the application type, select "External Application."
For the direction, select "Incoming."
For the redirect URL:
Click Save.
Copy the client ID and client secret. You will need these in the next steps.
Step 2: Configure the integration in Cortex
In Cortex, navigate to the .
Click Integrations from the main nav. Search for and select Bitbucket.
Click Add configuration.
Note: When using an on-premises configuration of Bitbucket, the language does not populate on .
Configure Bitbucket with Cortex Axon Relay
See Internally hosted integrations for instructions. Make sure to follow the Bitbucket-specific instructions for the docker-compose.yml file.
At the bottom of the side panel, click Save.
Alias is optional and only relevant if you have opted into multi account support
false
Name of integration (in this case, BITBUCKET)
✓
description
Description for the Bitbucket team
.NET (C#): packages.lock.json
Java: pom.xml
Go: go.sum
Weekly PRs merged
Avg PRs reviewed/week
repository
org/repo as defined in Bitbucket
true
basepath
If the entity is in a monorepo (e.g. in a subdirectory), use this field to define the subdirectory
false
type
Ownership type; must be defined as group for Bitbucket teams
In the Advanced settings, enable Domain-wide Delegation.
Under the Domain-wide Delegation setting, copy the client ID and store it in a secure location; you will need this in the next steps.
The service account should have the following permissions for each project to enable Google Cloud resources:
Google service account permissions
AI Platform → AI Platform Viewer, Dataform Viewer, Cloud Storage for Firebase Viewer, Data Catalog Viewer, Vision AI Viewer, Notebooks Viewer, Dataflow Viewer
Apigee → Cloud Api Hub Viewer
App Engine → App Engine Viewer
Artifact Registry → Artifact Registry Reader
BigQuery → BigQuery Metadata Viewer
BigQuery Connection → BigQuery Connection User
Cloud Asset → Cloud Asset Viewer
Cloud Asset → ListResource
Note: This permission is necessary to run services and jobs.
Click Integrations from the main nav. Search for and select Google.
Click Add configuration.
Configure the Google integration form:
Domain: Enter your Google domain.
Service account email: Enter the email address for the service account.
Credentials JSON: Enter the service account JSON key you created in the previous steps.
Click Save.
By default, a service will have dependencies on any resource with Google Cloud tag label = "service" and tag value = the service's Cortex tag. After saving your integration, you may customize the tag key name here by entering a new name into the Custom label key field. Leave it blank to use "service" as the key name.
Supported Google entity types
Cortex supports pulling in the following entity types from Google:
Supported Google entity types
Google Cloud Vertex AI Batch Prediction Job
Google Cloud Vertex AI Dataset
Google Cloud Vertex AI Endpoint
Google Cloud Vertex AI Featurestore
Google Cloud Vertex AI Index
Google Cloud Vertex AI Model
Google Cloud Vertex AI Model Deployment Monitoring Job
Google Cloud Vertex AI Notebooks Instance
Google Cloud Vertex AI Pipeline Job
Google Cloud Vertex AI Platform Index Endpoint
Google Cloud Vertex AI Specialist Pool
Google Cloud Vertex AI Study
Google Cloud Vertex AI Tensorboard
Google Cloud Vertex AI Training Pipeline
Google Cloud Vertex AI Vision Application
Google Cloud Vertex AI Vision Cluster
Google Cloud Vertex AI Vision Index Point
Google Cloud Vertex AI Vision Operator
Google Cloud Vertex AI Vision Processor
Google Cloud Apigee Api
Google Cloud Apigee Instance
Google Cloud App Engine Service
Google Cloud Artifact Registry Repository
Google Cloud BigQuery Connection
Google Cloud BigQuery
Google Cloud Composer Environment
Google Cloud Functions
Google Cloud Kubernetes Engine Clusters
Google Cloud Kubernetes Engine Operations
Google Cloud IAM Service Account
Google Cloud Instance Group
Google Cloud HTTP(S) Load Balancing
Google Cloud Memorystore Memcached
Google Cloud Memorystore Redis
Google Cloud Project
Google Cloud Run Job
Google Cloud Run Service
Google Cloud Spanner Instance
Google Cloud Spanner Instance Config
Google Cloud SQL
Google Cloud Storage
Google Cloud Pub/Sub Topics
Google Cloud VM Instances
Google Cloud VPC Serverless Connector
How to connect Cortex entities to Google
Enable automatic import of Google entities
You can configure automatic import from Google Cloud. Note that this setting does not include team entities.
Cortex can use Google Groups as an ownership provider, automatically syncing memberships from any Google Group mailing list.
Automatic Google dependency discovery
By default, Cortex will try to automatically discover dependencies between your entities and Google Cloud resources with a matching label. By default the label key that will be matched is service, however you can customize this key value in the Google Cloud Settings page.
If you'd like to explicitly define these Google Cloud dependencies, the x-cortex-dependency field should be a map, defined as follows:
Editing the entity descriptor
Groups
The value for name should be the full group email as defined in Google Groups.
Entities
Cortex uses the resource name and project ID to look up catalog entities in your Google Cloud account. Function resource names should be of the format location/function
View Google Cloud Observability data in entity pages
After integrating with Google, you will see data from Google Cloud Observability on entity details pages:
On an entity's overview page, see an overview of SLOs for the entity.
Click Monitoring > Google in an entity's sidebar to see more information about Google SLOs, including the SLO name, its targets, its status, the current value for that entity, and the period of time the SLO is being calculated for. For example, if the time listed is "7 days ago," then the SLO is looking at the time range starting 7 days ago to now.
Scorecards and CQL
With the Google integration, you can create Scorecard rules and write CQL queries based on GCP details, Google Cloud Observability SLOs, and Google teams.
A Scorecard might include a rule to verify that an entity has GCP details:
You might include a rule to check whether any labels on the GCP recourse are titled origin:
SLOs
SLOs associated with the entity via ID or tags. You can use this data to check whether an entity has SLOs associated with it, and if those SLOs are passing.
Definition:slos: List<SLO>
Example
In a Scorecard, you can use this expression to make sure an entity is passing its SLOs:
Use this expression to make sure latency Service Level Indicator (SLI) value is above 99.99%:
Ownership CQL
All ownership details
A special built-in type that supports a null check or a count check, used to enforce ownership of entities.
Definition:ownership: Ownership | Null
Example
An initial level in a security Scorecard might include a rule to ensure an entity has at least one team as an owner:
All owner details
List of owners, including team members and individual users, for each entity
Definition:ownership.allOwners()
Example
The Scorecard might include a rule to ensure that entity owners all have an email set:
Team details
List of teams for each entity
Definition:ownership.teams(): List<Team>
Example
The Scorecard might include a rule to ensure that an entity owners all have a description and are not archived:
View integration logs
This feature is available to Cortex cloud customers.
Cortex conducts an ownership sync for Google teams every day at 9 a.m. UTC.
Troubleshooting and FAQ
The GCP integration only supports a single service account. Can I work around this?
By default, GCP service accounts are restricted to the project they were created in. If other projects don’t explicitly allow that service account to access their resources, Cortex can’t collect data from them. To work around this, you can configure a principal service account and associate it with multiple projects in GCP. Once the service account is linked to other projects, Cortex can use that service account to pull data from multiple GCP projects.
After creating a service account that is linked to a project, open your second project in GCP and go to IAM & Admin > IAM > Click +Add. Using the service account ID that you already created, add a principal to the project. Repeat these steps for each project.
The following options are available to get assistance from the Cortex Customer Engineering team:
Email: [email protected], or open a support ticket in the in app Resource Center
Slack: Users with a connected Slack channel will have a workflow added to their account. From here, you can either @CortexTechnicalSupport or add a :ticket: reaction to a question in Slack, and the team will respond directly.
Don’t have a Slack channel? Talk with your Customer Success Manager.
Getting deployment data into Cortex is critically important for both engineering insights and organizational success. It enables the use of Eng Intelligence to assess DORA metrics and other KPIs to understand how quickly and efficiently your teams are shipping code. Deployment data also gives you the insight needed to create Scorecards and Initiatives that promote process improvement across teams.
To get deploys into Cortex, you must use the API endpoint.
Deploy data pipeline examples
In these examples, the repository secret or variable contains a valid , and the repository name matches the .
GitHub Action
In this example, a repository secret called CORTEX_TOKEN contains a valid Cortex API key.
GitLab pipeline
Make sure you have defined a CI/CD variable in GitLab that contains your Cortex API key, and ensure the repository you're running this in contains the package.json file.
If any stage in the pipeline fails, the entire pipeline fails and a ROLLBACK event is sent to Cortex.
Azure DevOps
In this example, a variable called CORTEX_TOKEN contains a valid Cortex API key.
Jenkins
In this example, it is assumed that the Jenkins job is associated with a repository. It uses the repository name to match with the Cortex entity tag. The job also assumes that you have defined a Global Credential called CORTEX_TOKEN that contains a valid Cortex API key.
Add custom data to deployments
Adding a customData object to your API call allows you the flexibility to add metadata that is important to your organization.
If custom data is included for a deploy, you can view it under "CI/CD > Deploys" on an . Click the "Details" drop-down to expand and view the custom data:
Viewing deploy data
View deployments on entity pages
Deployment information appears in several places on an entity page:
While viewing an entity page, you can see last deployment information near the top of the page:
Near the bottom of an entity page, deploys will also appear under "Recent activity."
In the left sidebar of an entity, click Events. This page includes:
View deployments in Eng Intelligence
When you send deploy data into Cortex, you can use this information in reporting to gain insight into your . Deploy metrics include average number of deploys per week and deploy change failure rate.
In Eng Intelligence, click into an entity to open a side panel with a historical performance graph.
Read more about using .
Use deployment data in CQL and Scorecards
You can use deploy data to write rules for and to create .
See more examples in the in Cortex.
Deploys
Deploys added to an entity through the .
Definition:deploys(lookback: Duration, types: List): List
Example
In a Scorecard, you can write a rule to check whether an entity had fewer than 5 bug fixes in the last month:
Write a rule to verify that there was, on average, less than 1 rollback for every 4 deploys in the past month:
By default the chart shows data from the last month. Click the Last month dropdown in the upper right to change the timeframe.
All recent events for the entity. In the upper right corner of the events list, click Filter to select and apply filters for this list. You can choose to only view the deploy event types. \
On an entity page, click "Events" in the sidebar to view recent events.
Use GitLab metrics in to understand key metrics and gain insight into services, incident response, and more
Create to monitor development maturity relating to GitLab projects
How to configure GitLab with Cortex
There are two options for integrating GitLab: the default configuration method and Cortex Axon Relay, a relay broker allows you to securely connect your on-premises GitLab data.
Prerequisites
Before getting started:
A GitLab user with at least the Maintainer role must create a GitLab or with the read_api scope.
We recommend that you create the token at the parent group level, as GitLab does not support using a scoped token to read members from a parent group. If you do not create the token at the parent level, then you will need to manually configure groups in your GitLab settings in order for identity mapping and teams to work as expected.
Self-hosted prerequisites
If you're using a self-hosted instance of GitLab, you'll need to verify that your Cortex instance is able to reach the GitLab instance.
We route our requests through a static IP address. Reach out to support at to receive details about our static IP. If you're unable to directly allowlist our static IP, you can route requests through a secondary proxy in your network that has this IP allowlisted and have that proxy route traffic to your GitLab instance.
Configure the integration in Cortex
In Cortex, navigate to the :
Click Integrations from the main nav. Search for and select GitLab.
Once you save your configuration, you'll see it listed on the integration's settings page in Cortex. If you’ve set everything up correctly, you’ll see the option to Remove Integration in Settings.
You can also use the Test all configurations button to confirm that the configuration was successful. If your configuration is valid, you’ll see a banner that says “Configuration is valid. If you see issues, please see documentation or reach out to Cortex support.”
Configure the integration for multiple GitLab accounts
The GitLab integration has multi-account support. You can add a configuration for each additional by repeating the process above.
Each configuration requires an alias, which Cortex uses to correlate the designated with registrations for various entities. Registrations can also use a default configuration without a listed alias. You can edit aliases and default configurations from the GitLab page in your Cortex settings. Select the edit icon next to a given configuration and toggle Set as default on. If you only have one configuration, it will automatically be set as the default.
Cortex supports mapping multiple identities for a single user if you have multiple configurations of GitLab. See the for more information.
Enable GitOps for your GitLab integration
Cortex supports a GitOps approach, which allows you to manage entities in Cortex through your version control system. If you would prefer this workflow over the UI for the GitLab integration, you must create a webhook. Please see the for instructions.
How to connect Cortex entities to GitLab
Import entities
Cortex will discover entities for import from your GitLab configuration(s). These will appear in the import entities workflow.
See the for instructions on importing entities manually.
Editing the entity descriptor
Git
By specifying the x-cortex-git field in your Cortex entity descriptor, you'll be able to see Git information in the entity page, including the top language, recent commits, and top contributors.
Field
Description
Required
Only one repository can be defined for in a given entity's YAML in the x-cortex-git block.
Ownership
You can define the following block in your Cortex entity descriptor to add your GitLab groups.
Team name should match the group name in GitLab.
Field
Description
Required
Identity mapping
Cortex maps users' email addresses to discovered GitLab accounts, so you never need to define email ownership in an entity descriptor.
You can confirm users' GitLab accounts are connected from .
If users are not loading in the identity mapping page, make sure that you have created your GitLab personal access token from the parent level as described in the .
Using the GitLab integration
View GitLab data on entity pages in Cortex
Cortex uses the GitLab integration for a significant amount of data that appears on .
The GitLab integration will populate the Repo and Language detail blocks on an entity's details page.
In the Recent activity preview, you'll find the recent commits and releases. These will also appear in the event timeline.
These data will appear for entities imported from a Git source or those that have a Git repo defined in their YAMLs.
Events
On an entity's Events page, you can find all of the commits and releases associated with that entity. Each is hyperlinked to the commit or release page in GitLab and includes a timestamp.
CI/CD
To see pipeline runs for GitLab, use the to add deploy information. After doing this, from the CI/CD > Deploys page in the entity's sidebar, you will see a history of pipeline runs.
Repository
You can access more detailed information pulled from GitLab in the Repository page in the entity's sidebar. At the top of the page, you'll find the repo associated with that entity and the most-used language in files for that entity. In the Top contributors block, you'll find the three users who have contributed the most code and the number of their contributions.
In the Commits section, you'll find the 10 most recent commits and metadata about each. Below Commits is the Recent releases section, which includes the 5 most recent releases.
Packages
Packages are automatically scraped from your Git repos or they can be submitted via the . The package file must be in the root of your repository — or, if you're using basepath, in the root of the subdirectory — to be scraped by Cortex. You can query an entity's packages in using packages().
To view packages, click Packages in the entity's sidebar.
The following package types are automatically scraped from repositories:
All other files of these types can be added via the .
Team pages
When a GitLab team is registered in a team entity descriptor, Cortex will pull GitLab users in to the Members tab. When available, Cortex will pull in the profile picture and email address for each user.
If team members are not appearing as expected, make sure that you have created your GitLab personal access token from the parent level as described in the .
Engineering homepage
The GitLab integration enables Cortex to pull information about merge requests into the . You can find your open merge requests and any merge requests assigned to you for review.
Merge requests from GitLab are refreshed every 2 minutes.
Eng Intelligence
The also uses merge request data from GitLab to generate metrics:
Average MR open to close time
Avg time to first review
Avg time to approval
MRs opened
You can read more about how Eng Intelligence tracks metrics for teams and users in the Eng Intelligence walkthrough.
To add deployments for your GitLab related entity, you can send a deployment event to the .
Scorecards and CQL
With the GitLab integration, you can create Scorecard rules and write CQL queries based on GitLab data.
See more examples in the in Cortex.
Approvals required to merge
Number of approvals required to merge a pull/merge request into a repository. Defaults to 0 if no approvals are defined.
Definition: git.numOfRequiredApprovals()
Examples
For a security or development maturity Scorecard, you can write a rule to make sure at least one approval is required to merge a pull/merge request:
Git repository set
Check if an entity has a registered Git repository.
Definition:git (==/!=) null: Boolean
Example
In a Scorecard, you can write a rule that detects whether an entity has a Git repository set:
Pipeline build success rate
The percentage of build pipelines that complete successfully. This is calculated against builds on the default branch, for commits in the last 30 days. The calculation is # successful builds / (# successful + # failed).
Definition:git.percentBuildSuccess(): Number
Example
In a Scorecard, you can write a rule that requires at least 90% of build runs to be successful:
Branches
List all live branches with some basic metadata.
Head
Is protected
Branch protection details
Find details for specified branch, or default branch if none is specified.
Branch name
Code owner reviews required
Commits
Get the latest commits (to a maximum of 100) for a defined lookback period (defaulting to 7 days).
Date
Message
Default branch
Default branch for the repository, or main when null.
Definition:git.defaultBranch()
Example
If default branches should always be named "main," you can write a rule to make sure entities follow this practice:
File contents
Load the contents of a file from the entity's associated repository.
The contents can be validated by using string comparison operations or parsed by the built-in jq function. The jq function will automatically coerce file contents of JSON or YAML formats.
Definition:git.fileContents()
Example
For a Scorecard focused on development maturity, you could use the
File exists
Check if file exists from within the entity's associated repository.
Definition:git.fileExists()
Examples
For a Scorecard focused on best practices, you can make sure that repositories contain a README.md file:
This rule would make sense in the first level because it's so essential.
Number of Git vulnerabilities
Check the number of vulnerabilities for an entity's associated repository.
Definition:git.numOfVulnerabilities()
Examples
A security-focused Scorecard will likely include a rule making sure there are no Git vulnerabilities:
You can use Scorecard levels to stratify vulnerabilities by risk. An initial level might make sure there are no critical vulnerabilities:
List of Git vulnerabilities
Find all vulnerabilities within a repository. Can filter by severity or scan type.
Definition: git.vulnerabilities()
Examples
You could write a Scorecard rule that verifies an entity has fewer than 5 Git vulnerabilities:
You could write a rule to verify that an entity has no critical vulnerabilities:
Has Cortex YAML
Check if a repository has a valid cortex.yaml file checked in at the root directory (when GitOps is enabled).
Definition:git.hasCortexYaml()
Example
If you're using a Scorecard to track a migration from Cortex UI to GitOps, you can use this rule to make sure entities are set up for GitOps management of entity descriptors:
Last commit details
Provides last commit details.
Date
Message
Pull requests
Lists pull requests opened during a defined lookback period.
Approval date
Author
Reviews
List reviews left during a defined lookback period.
Organization
Repository
Workflow runs
Get workflow runs meeting given filter criteria, including conclusions, statuses, and a lookback period.
Conclusion
Name
Ownership CQL
All ownership details
A special built-in type that supports a null check or a count check, used to enforce ownership of entities.
Definition:ownership: Ownership | Null
Example
An initial level in a security Scorecard might include a rule to ensure an entity has at least one team as an owner:
All owner details
List of owners, including team members and individual users, for each entity
Definition:ownership.allOwners()
Example
The Scorecard might include a rule to ensure that entity owners all have an email set:
Team details
List of teams for each entity
Definition:ownership.teams(): List<Team>
Example
The Scorecard might include a rule to ensure that an entity owners all have a description and are not archived:
View integration logs
This feature is available to Cortex cloud customers.
On the integration settings page, click the Logs tab to view logs from the last 7 days. Learn more in .
Background sync
Cortex conducts a background sync of GitLab identities every day at 10 a.m. UTC. Merge requests are refreshed every 2 minutes.
FAQ and Troubleshooting
Why is my CQL query git.branchProtection() returning no results or a 403 error?
This can happen if you do not have the read_api scope set for your access token, or if the GitLab user who generated the token does not have at minimum the Maintainer role.
Still need help?
The following options are available to get assistance from the Cortex Customer Engineering team:
Email: , or open a support ticket in the in app Resource Center
Slack: Users with a connected Slack channel will have a workflow added to their account. From here, you can either @CortexTechnicalSupport or add a :ticket: reaction to a question in Slack, and the team will respond directly.
Don’t have a Slack channel? Talk with your Customer Success Manager.
If you're using the Scaffolder for entities in a given GitLab instance, make sure that configuration has the full api scope.
Click Add configuration.
Configure the GitLab integration form:
Account alias: Enter the alias you will use to tie entity registrations to different configuration accounts.
Token: Enter your personal or group access token.
Host: Enter your host. If using a custom GitLab instance, enter the URL without the API path (e.g. https://gitlab.getcortexapp.com)
Hide personal projects: Toggle this setting on if you do not want your personal projects pulled in to Cortex. Toggle this setting off to allow Cortex to pull your personal projects.
Click Save.
Configure GitLab with Cortex Axon Relay
See Internally hosted integrations for instructions. Make sure to follow the GitLab-specific instructions for the docker-compose.yml file.
Alias for the configuration in Cortex (only needed if you have opted into multi-account support)
Name of integration (in this case, GITLAB)
✓
description
Description for the GitLab team
.NET (C#): packages.lock.json
Java: pom.xml
Go: go.sum
Weekly MRs merged
Avg MRs reviewed/week
Avg commits per MR
Avg lines of code changed per MR
By having a rigorous PR process in place for a repo, you can make sure changes aren't made that create vulnerabilities. This kind of rule could also be used in a best practices or project standards Scorecard.
You can also use a similar expression in the Query Builder to find entities lacking approval:
Name
Definition: git.branches()
Example
For a best practices Scorecard, you can make sure that branches associated with an entity match a standard naming convention:
Dismiss stale reviews
Required status checks
Restrictions apply to admin
Review required
Definition:git.branchProtection()
Examples
For a security Scorecard, you can write a rule to make sure the default branch is protected:
Because vulnerabilities in the default branch are critical, this rule should be in one of the first couple levels.
You can also use the Query Builder to find entities with unprotected default branches:
SHA
URL
Username
These results can be filtered based on branch name, using the default branch if no other branch is provided.
Definition:git.commits()
Example
You can use the git.commits() expression in a security Scorecard to make sure entities have fewer than three commits to a "security-fixes" branch in the last week:
Entities passing this rule will include those that haven't needed three or more security fixes. This can indicate that there aren't vulnerabilities in a given entity's code, but could also suggest that fixes aren't being implemented. Using this rule in conjunction with one focused on vulnerabilities could provide the extra context needed to gain a better understanding of what's happening.
git.fileContents()
rule to enforce that a CI pipeline exists, and that there is a testing step defined in the pipeline.
A best practices Scorecard, meanwhile, could use this expression for a number of rules:
To make sure node engine version in specified in the package.json file:
To make sure TypeScript projects have a tsconfig.json file checked in:
To make sure projects using yarn do not allow NPM:
And to ensure the yarn version being used is not deprecated:
A higher-level rule in a best practices Scorecard might confirm that developers are checking in lockfiles to ensure consistency in package installs:
And/or a rule that makes sure there are unit tests enabled:
Finally, you could write a rule to make sure projects have a standard linter:
While a higher level might make sure there are no vulnerability warnings:
SHA
URL
Username
Definition:git.lastCommit()
Examples
One of the first rules you might write for a Scorecard focused on development maturity or security is one validating that the last commit was within the last month:
As counterintuitive as it may seem, services that are committed too infrequently are actually at more risk. People who are familiar with the service may leave a team, institutional knowledge accumulates, and from a technical standpoint, the service may be running outdated versions of your platform tooling.
Depending on best practices at your organization, you may want to confirm entities are updated within a week:
Confirming whether a service was updated within the last week can help team members catch outdated code sooner. Plus, if there is a security issue, you can quickly determine which services have or have not been updated to patch the vulnerability.
Date closed
Date opened
First review date
Last updated
Number of commits
Number of lines added
Number of lines deleted
Organization
Repository
Source
Status
URL
Definition:git.pullRequests()
Example
You can use the git.pullRequests() query to find entities that have a small number of pull requests opened in the last two weeks:
This can highlight entities that haven't been updated recently, which may be especially useful when entities have to be updated to address a vulnerability.
Review date
Reviewer
Definition:git.reviews()
Examples
A development maturity Scorecard might use the git.reviews() expression to make sure that there is a rigorous review process in place before changes are implemented:
This rule makes sure that there are more than 25 reviews left in the last week.
Run started at
Run time
Run updated at
Status
Conclusions: FAILURE, SUCCESS, TIMED_OUT
Statuses: QUEUED, IN_PROGRESS, COMPLETED
The lookback period specifies a duration for which returned runs should be created within, defaulting to a period of 3 days.
The runTime of the WorkflowRun object represents the difference between runStartedAt and runUpdatedAt times in seconds.
Definition:git.workflowRuns()
Example
To make sure an entity has had a successful workflow run within the last two weeks, you can write a rule like:
This rule is checking for GitHub workflow runs with a SUCCESS conclusion and COMPLETED status during a 14-day lookback window.
repository
GitLab project ID or namespace/repo as defined in GitLab
✓
basepath
Subdirectory for the entity if it is in a monorepo
type
Ownership type; must be defined as group for GitLab teams
Whether you use the to , every entity in your Cortex catalogs is defined by a YAML file called the Cortex entity descriptor, also referred to as an entity's Cortex YAML (stemming from cortex.yaml, the name of the file that powers the .)
Each file is a fully compliant OpenAPI 3 spec file, with our own Cortex-specific extensions.
You can still use Cortex if you don't use OpenAPI/Swagger. We use the OpenAPI spec as a base for entity metadata, since it's an open spec with official support for extensions. That lets us extend it to be an entity descriptor spec with optional usage of actual OpenAPI fields.
Azure DevOps is a Microsoft-owned version control system used for managing the software development lifecycle.
Integrating Cortex with Azure DevOps allows you to:
Automatically discover and track ownership of Azure DevOps entities
Follow a GitOps workflow with Azure DevOps
View information about your Azure DevOps repositories on an entity's details page, including: The repo associated with the entity, recent commits and releases in the event timeline, the most-used language in the files for that entity, the top code contributors, and their number of contributions
If you pull in , you can also see pipeline runs and builds in the CI/CD section of an entity's details page.
If you enable the , you will also see a list of open work items on entity pages.
View information about pull requests and work items in the engineering homepage
in Cortex
Use Azure DevOps metrics in Eng Intelligence to understand key metrics and gain insight into services, incident response, and more
Create that track progress and drive alignment on projects involving your repositories, Azure DevOps work items, and Azure DevOps pipeline data
How to configure Azure DevOps with Cortex
Configure the integration in Cortex
You can configure Azure DevOps with a Personal Access Token (PAT) or with a Service Principal with Entra ID.
Prerequisite
Before you get started:
Add a with at least the following scopes enabled:
Analytics: read
Cortex supports mapping multiple identities for a single user if you have multiple configurations of Azure DevOps. See the for more information.
Enable or disable Azure DevOps work items
On the , you can choose whether Azure DevOps work items should be pulled in from Azure DevOps. Cortex recommends disabling this option if your organization does not use work items or if you are worried about running into rate limit issues.
How to connect Cortex entities to Azure DevOps
Import entities from Azure DevOps
See the for instructions on importing entities.
Editing the entity descriptor
In an entity's YAML, you can define a , , , and .
Define a repository
To define an Azure DevOps repository for a given entity, add the x-cortex-git block to the entity's descriptor.
Field
Description
Required
Only one repository can be defined for in a given entity's YAML in the x-cortex-git block.
Define work items
Before adding work items to your entity YAML, make sure you have in your integration settings.
To define Azure DevOps work items for a given entity, add the x-cortex-azure-devops block to the entity's descriptor. If there is no work item registrations, but the entity matches a repository, we will pull in all work items from the repository's project with a tag that matches the Cortex entity name, , or the repository name.
Example WIQL
The example YAML below is based on the following example WIQL:
Learn more about WIQL in .
Field
Description
Required
Define ownership
Ownership of each entity through Azure DevOps is defined through an owner of type group.
name is a case-sensitive field that corresponds to the upstream identifier of your owner from Azure DevOps.
Learn more about ownership in .
Define pipelines
You can add Azure DevOps pipelines under the x-cortex-azure-devops block:
Field
Description
Required
Learn more about Azure DevOps pipelines in .
Identity mappings for Azure DevOps
Cortex maps users' email addresses to discovered Azure DevOps accounts.
You can confirm users' Azure DevOps accounts are connected from .
Create a work item from an Initiative issue
Initiatives allow you to set deadlines for specific rules or a set of rules in a given Scorecard and send notifications to users about upcoming due dates.
From the Issues tab of an Initiative, you can automatically create a Azure DevOps work item from a failing rule:
Click Create issue.
In the modal that appears, fill out the form:
Integration: If you have multiple task tracking tools, select Azure DevOps from the Integration dropdown.
The issue configuration will apply to all entities that meet the filter criteria. Once an entity is passing the rule, Cortex will automatically close the associated ticket.
Using the Azure DevOps integration
View Azure DevOps data on entity pages in Cortex
The Azure DevOps integration will populate the Repo detail block on an entity's details page.
In the Recent activity preview, you'll find the recent commits and releases. These will also appear in the event timeline.
These data will appear for entities imported from a Git source or those that have a Git repo defined in their YAMLs.
Events
On an entity's Events page, you can find all of the commits and releases associated with that entity. Each is hyperlinked to the commit or release page in Azure DevOps and includes a timestamp.
CI/CD
From the CI/CD > Deploys page in the entity's sidebar, see a history of pipeline runs.
Repository
You can access more detailed information pulled from Azure DevOps under Repository in the sidebar. At the top of the repository page, you'll find the repo associated with that entity and the most-used language in files for that entity. In the Top contributors block, you'll find the three users who have contributed the most code and the number of their contributions.
In the Commits section, you'll find the 10 most recent commits and metadata about each. Below Commits is the Recent releases section, which includes the 5 most recent releases.
Issue tracking
In the Issue tracking section, you can find a list of open . Each work item will show the title, summary, assignees, priority, and date created.
Packages
Packages are automatically scraped from your Git repos or they can be submitted via the . The package file must be in the root of your repository — or, if you're using basepath, in the root of the subdirectory — to be scraped by Cortex. You can query an entity's packages in using packages().
To view packages, click Packages in the entity's sidebar.
The following package types are automatically scraped from repositories:
All other files of these types can be added via the .
Engineering homepage
The Azure DevOps integration enables Cortex to pull information about pull requests and work items into the . You can find your open pull requests, any pull requests assigned to you for review, and any work items assigned to you.
Pull requests and work items from Azure DevOps are refreshed every 5 minutes.
Eng Intelligence
The also uses pull request data from Azure DevOps to generate metrics:
Average PR open to close time
Avg time to first review
Avg time to approval
PRs opened
Read more about how Eng Intelligence tracks metrics for teams and users in the .
Scorecards and CQL
With the Azure DevOps integration, you can create Scorecard rules and write CQL queries based on Azure DevOps work items.
See more examples in the in Cortex.
Approvals required to merge
Total number of approval required to merge a pull request into a repository. Defaults to 0 if no approvals are defined.
Definition:git.numOfRequiredApprovals()
Examples
For a security or development maturity Scorecard, you can write a rule to make sure at least one approval is required for a pull request:
Branches
List all live branches with some basic metadata:
Head
Is protected
Branch protection details
Find details for a specified branch or default branch if none is specified.
For a security Scorecard, you can write a rule to make sure the default branch is protected:
Or to make sure the main branch is protected:
Commits
Get the latest commits (to a maximum of 100) for a defined lookback period (defaulting to 7 days).
These results can be filtered based on branch name, using the default branch if no other branch is provided.
Definition:git.commits()
Examples
You can use the git.commits()
Default branch
Default branch for the entity's repository or main when null.
Definition:git.defaultBranch()
Examples
If default branches should always be named "main," you can write a rule in a best practices Scorecard to make sure entities are compliant:
File contents
Load the contents of a file from the entity's associated repository.
The contents can be validated by using string comparison operations or parsed by the built-in jq function. The jq function will automatically coerce file contents of JSON or YAML formats.
Definition:git.fileContents(<filename: Text>)
File exists
Check if file exists from within the entity's associated repository.
Definition:git.fileExists(<filename: Text>)
Examples
For a development best practices Scorecard, this expression can be used for a rule that makes sure developers are checking in lockfiles to ensure repeatable builds:
In the Query builder, you can use this expression with a wildcard to find entities with unit tests enabled:
Has Cortex YAML (GitOps)
When enabling GitOps to manage entity descriptors, Cortex checks for a checked in file ./cortex.yaml at the root directory. This rule can help track migrations from UI editing to GitOps for entity descriptor management.
Definition:git.hasCortexYaml()
Examples
If you're using a Scorecard to track a migration from Cortex UI to GitOps, you can use this rule to make sure entities are set up for GitOps management of entity descriptors:
Git repository set
Check if entity has a registered Git repository.
Definition:git (==/!=) null
Examples
A Scorecard focused on best practices or standards will likely include a rule in its first level making sure a Git repository is set up:
If an entity is failing this rule, it can indicate broader issues with the integration or explain why an entity isn't functioning as expected.
Last commit details
Provides last commit details.
Definition:git.lastCommit()
Examples
Depending on best practices at your organization, you may want to confirm the last commit for a given entity is no older than 3 days:
Confirming whether a service was updated recently can help team members catch outdated code sooner. Plus, if there is a security issue, you can quickly determine which services have or have not been updated to patch the vulnerability.
List pipelines
List pipelines with metadata, including name, id, url, and project name.
Definition: azureDevops.pipelines()
Examples
You could write a Scorecard rule to ensure that the entity has at least 1 pipeline that scans vulnerabilities:
You could write a Scorecard rule to ensure that the entity has an Azure DevOps pipeline set:
Pipeline build success rate
Percentage of build pipelines that complete successfully.
This is calculated against builds on the default branch for commits in the last 30 days: # successful builds / (# successful + # failed).
Definition:git.percentBuildSuccess()
Examples
Pipeline metrics
List pipelines with metrics. Metrics contains the successRate & averageDuration of a pipeline.
Definition: azureDevops.pipelineMetrics()
Examples
You could write a Scorecard rule to ensure pipelines have a successRate higher than 95%:
Pipeline runs
Get pipelines runs meeting the given filter criteria, which includes results, states. Results include "succeeded", "failed", "canceled", "unknown", states include "completed", "inProgress", "canceling", "unknown".
Definition: azureDevops.pipelineRuns()
Examples
List pipeline runs that are opened and reviewed within 1 day:
Recency of last commit
Calculates the duration of time between Scorecard evaluation and the date of the last commit from the entity's Git repository.
Definition:git.lastCommit().freshness
Examples
One of the first rules you might write for a Scorecard focused on development maturity or security is one validating that the last commit was within the last month:
Reviews
List reviews left during a defined lookback period.
Organization
Repository
Search repository files
Find all instances of code search query from within a repository.
Can filter by path, file name (extension required in file name), or extension. Filters can use * for glob matching. Supplying a query is required.
Find top used language for a repository, if available.
Definition:git.topLanguage()
Examples
Let's say the primary language developers should be using is Kotlin. You can write a rule to make sure that the top language associated with entities is Kotlin:
You can also use this expression to query for entities that don't have Kotlin as the top language to identify those that need to be updated:
Work items
Number of unresolved work items associated with the entity, where unresolved is defined as the WIQL [System.State] NOT IN ('Closed', 'Done', 'Completed', 'Inactive', 'Removed').
Definition:azureDevops.workItems()
Examples
For a Scorecard measuring entity maturity, you can use this expression to make sure entities have fewer than 10 Azure DevOps work items:
Work items from WIQL query
Number of work items associated with the entity based on arbitrary WIQL query.
Definition:azureDevops.workItems(query: Text | Null)
Examples
For a more specific rule in an entity maturity Scorecard, you can use this expression with a WIQL query to make sure entities have no more than 3 tickets with "Doing" status and highest priority.
View integration logs
This feature is available to Cortex cloud customers.
On the integration settings page, click the Logs tab to view logs from the last 7 days. Learn more in .
Background sync
Cortex conducts a background sync of Azure DevOps identities every day at 10 a.m. UTC. Pull requests and work items are refreshed every 5 minutes.
Still need help?
The following options are available to get assistance from the Cortex Customer Engineering team:
Email: , or open a support ticket in the in app Resource Center
Slack: Users with a connected Slack channel will have a workflow added to their account. From here, you can either @CortexTechnicalSupport or add a :ticket: reaction to a question in Slack, and the team will respond directly.
Don’t have a Slack channel? Talk with your Customer Success Manager.
## API Spec and Version
openapi: 3.0.0
# Service Descriptors
# Required fields: info, title, x-cortex-tag
info:
title: <HUMAN_READABLE_SERVICE_NAME>
x-cortex-tag: <SERVICE_TAG>
description: <DESCRIPTION>
# Groups
# !Groups must contain only alphanumeric characters, and may not contain whitespaces!
x-cortex-groups:
- <GROUP_NAME>
- <GROUP_NAME>
- <GROUP_NAME>
# Owners
x-cortex-owners:
- type: group
name: my-team
provider: CORTEX # Use when referring to a team defined in Cortex; these teams do not map to identities from integrations
description: This is a description for this owner
- type: email
email: [email protected] description: This is a description for this owner
- type: group
name: team-name
provider: ACTIVE_DIRECTORY | AZURE_DEVOPS | BAMBOO_HR | GITHUB | GITLAB | GOOGLE | OKTA | OPSGENIE | SERVICE_NOW | WORKDAY
# Also see the team entity example below
# Links
x-cortex-link:
- name: <HUMAN_READABLE_NAME>
type: <TYPE>
url: <URL_TO_LINK>
description: <DESCRIPTION>
## Note that type of OPENAPI/ASYNC_API will be displayed in the API Explorer tab in the Cortex UI
## Links support relative URLs
# Dashboards
x-cortex-dashboards:
embeds:
- type: <datadog | grafana | newrelic>
url: <URL>
# Custom Data
x-cortex-custom-metadata:
my-key: the value
another-key:
this: is
an: object
my-key-2:
value: the actual value for the key
description: This is the description
final-key:
- also
- use
- lists!
# Custom entities
# You cannot create a custom entity type via GitOps, but after creating the type in the UI or API, you can create custom entities via GitOps.
title: Sally S
description: Technical writer
x-cortex-tag: employee-sally
x-cortex-type: org-employees
x-cortex-definition:
location: San Diego
department: Engineering
# Parent and child relationships
x-cortex-type: team
x-cortex-children:
- tag: child-team-1
- tag: child-team-2
x-cortex-type: domain
x-cortex-parents:
- tag: parent-team-1
- tag: parent-team-2
# Entity relationships
x-cortex-relationships:
- type: relationship-type-name
destinations:
- tag: destination-entity-1
- tag: destination-entity-2
# Dependencies
# Required fields: x-cortex-tag, method (required if path present), path (required if method present)
x-cortex-dependency:
- tag: <TAG>
method: <HTTP_METHOD>
path: <PATH_FOR_METHOD>
description: <DESCRIPTION>
metadata:
tags:
- <TAG_1>
- <TAG_2>
prod: true
# Team configurations
title: Eng Team
x-cortex-tag: eng-team
x-cortex-type: team
x-cortex-team:
groups:
- name: eng-team
provider: OKTA
members:
- name: Eng Manager
email: [email protected] notificationsEnabled: true
- name: Product Manager
email: [email protected] notificationsEnabled: false
x-cortex-children:
- tag: infra-team
- tag: sre-team
# Domain configurations
x-cortex-type: domain
x-cortex-owners:
- type: GROUP
name: cortexapps/engineering
provider: GITHUB
interitance: APPEND | FALLBACK | NONE
x-cortex-children:
- tag: chat-service
tag: chat-database
# Integrations
# Apiiro
x-cortex-apiiro:
repositories:
- alias: alias-one
repositoryId: repository-one
- alias: alias-two
repositoryId: repository-two
applications:
- alias: alias-one
applicationId: application-one
- alias: alias-two
applicationId: application-two
# AWS Cloud Control types
x-cortex-infra:
aws:
cloudControl:
- type: AWS::RDS::DBInstance
region: us-west-2
accountId: "123456123456"
identifier: rds-example
# AWS ECS
x-cortex-infra:
aws:
ecs:
- clusterArn: <CLUSTER_ARN>
serviceArn: <SERVICE_ARN>
- clusterArn: <CLUSTER_ARN_2>
serviceArn: <SERVICE_ARN_2>
# Azure DevOps
x-cortex-git:
azure:
project: <project-name>
repository: <repository-name>
# Azure Resources
x-cortex-azure:
ids:
- id: /subscriptions/1fbb2da1-2ce7-45e4-b85f-676ab8e12345/resourceGroups/GROUP1/providers/Microsoft.Compute/disks/vm1_disk1_3d9f85717666435e9e87e4883d31a7e9
alias: my-default-alias # alias is optional and only relevant if you have opted into multi account support
- id: /subscriptions/1fbb2da1-2ce8-45e4-b85f-676ab8e12345/resourceGroups/GROUP2/providers/Microsoft.Compute/disks/vm1_disk1_3d9f85717666435e9e87e4883d31a7e0
alias: my-other-alias # alias is optional and only relevant if you have opted into multi account support
# BambooHR
x-cortex-owners:
- type: group
name: <TEAM_NAME>
provider: BAMBOO_HR
description: # optional
# Bitbucket
x-cortex-git:
bitbucket:
repository: <workspace>/<repo>
x-cortex-owners:
- type: group
name: <TEAM_NAME>
provider: BITBUCKET
description: # optional
# Bugsnag
x-cortex-bugsnag:
project: <PROJECT_KEY> # projectKey in Bugsnag
# Buildkite
x-cortex-ci-cd:
buildkite:
pipelines:
- slug: my-buildkite-pipeline-slug-1
- slug: my-buildkite-pipeline-slug-2
tags:
- tag: my-buildkite-tag-1
- tag: my-buildkite-tag-2
# Checkmarx
x-cortex-checkmarx:
projects:
- projectName: My Cool Project
- projectId: 1234
# CircleCI
x-cortex-circle-ci:
projects:
- projectSlug: circleci-projectslug # projectslug in CircleCI
alias: circleci-alias # alias is optional and only relevant if you have opted into multi account support
# ClickUp
x-cortex-issues:
clickup:
spaces:
- identifier: 123456789
identifierType: ID
folders:
- identifier: my-folder
identifierType: NAME
tags:
- name: tag a
- name: tag b
# Codecov
x-cortex-static-analysis:
codecov:
owner: org-name
repo: my-project
provider: AZURE_DEVOPS | BITBUCKET | BITBUCKET_SERVER | GITHUB | GITHUB_ENTERPRISE | GITLAB | GITLAB_ENTERPRISE
flag: flag
# Coralogix
x-cortex-coralogix:
applications:
- applicationName: my-app # application name tied to alert
alias: my-alias # alias is optional and only relevant if you have opted into multi account support
# Datadog
x-cortex-apm:
datadog:
serviceTags: # List of tags & values
- tag: <KEY>
value: <VALUE>
- tag: <KEY>
value: <VALUE>
. serviceName: <NAME IN DATADOG>
monitors:
- monitor-id
- monitor-id-2
x-cortex-slos:
datadog: # List of SLO ids
- id: slo-id-1
- id: slo-id-1
# Dynatrace
x-cortex-apm:
dynatrace:
entityIds:
- mock-service-id-1
- mock-service-id-2
entityNameMatchers:
- "foo.*"
x-cortex-slos:
dynatrace:
- id: slo-id-1
- id: slo-id-2
# Entra ID (Azure Active Directory)
x-cortex-owners:
- type: group
name: <TEAM_NAME>
provider: ACTIVE_DIRECTORY
description: # optional
# FireHydrant
x-cortex-firehydrant:
services:
- identifier: ASDF1234
identifierType: ID
- identifier: service-slug
identifierType: SLUG
# GitHub
x-cortex-git:
github:
repository: <org>/<repo>
basepath: <SERVICE_NAME> # optional
x-cortex-owners:
- type: group
name: <ORGANIZATION>/<TEAM> # Must be of form <org>/<team>
provider: GITHUB
description: # optional
# GitLab
x-cortex-git:
gitlab:
repository: <namespace>/<project>
basepath: <SERVICE_NAME> # optional
x-cortex-owners:
- type: group
name: Team Name
provider: GITLAB
description: This is a description for this owner
# Google
x-cortex-owners:
- type: group
name: <GROUP_NAME>
provider: GOOGLE
x-cortex-dependency:
gcp:
labels:
- key: my-key-1
value: my-value-1
- key: my-key-2
value: my-value-2
x-cortex-infra:
Google Cloud:
resources:
- resourceName: location/function
projectId: project1
resourceType: function
- resourceName: example-bucket
projectId: project1
resourceType: storage
x-cortex-slos:
gcp:
- projectId: cortex-gcp-integration
serviceId: iLE2e4HvR_iVlxAaBbCc12
- projectId: cortex-gcp-integration
serviceId: adfdfdafd
# Grafana
x-cortex-dashboards:
embeds:
- type: grafana
url: <embed_url_to_dashboard>
# incident.io
x-cortex-incident-io:
customFields:
- name: Entity
value: My Entity
alias: my-default-alias
- id: Entity_ID
value: my-second-entity
alias: my-other-alias
# Jira
x-cortex-issues:
jira:
labels:
- <LABEL1>
- <LABEL2>
components:
- <COMPONENT1>
projects:
- project1
# Optional: Override Cortex default Jira query
defaultJql: 'status = "In Progress"'
# Kubernetes
x-cortex-k8s:
deployment:
- identifier: namespace/name
cluster: dev # optional
- identifier: experiment/scratch
cluster: dev
- identifier: default/cortex
cluster: prod
argorollout:
- identifier: namespace/name
cluster: dev
statefulset:
- identifier: namespace/name
cluster: dev
cronjob:
- identifier: namespace/name
cluster: dev
# LaunchDarkly
x-cortex-launch-darkly:
projects:
- key: project-key
environments: # Optional
- environmentName: prod
- environmentName: staging
alias: alias-1 # alias is optional and only relevant if you have opted into multi account support
- tag: project-tag
environments: # Optional
- environmentName: prod
alias: alias-2 # alias is optional and only relevant if you have opted into multi account support
feature-flags:
- tag: feature-flag-tag
environments: # Optional
- environmentName: staging
alias: alias-3 # alias is optional and only relevant if you have opted into multi account support
# Lightstep
x-cortex-slos:
lightstep:
- streamId: <STREAM_ID>
targets:
latency:
- percentile: <PERCENTILE>
target: <TARGET>
slo: <SLO>
# Mend
x-cortex-static-analysis:
mend:
applicationIds:
- mend_id_1
- mend_id_2
projectIds:
- project_id_1
- project_id_2
# Microsoft Teams
x-cortex-microsoft-teams:
channels:
- name: team-engineering
teamName: engineering
description: This is a description for the engineering channel in Teams.
notificationsEnabled: true
# New Relic
x-cortex-apm:
newrelic:
applications:
- applicationId: <APP_ID>
alias: default-app
tags:
- tag: tagKey
value: tagValue
alias: default-app
x-cortex-dashboards:
embeds:
- type: newrelic
url: <FULL_URL_TO_DASHBOARD>
# Okta
x-cortex-owners:
- type: group
name: <GROUP_NAME> # group name in Okta
provider: OKTA
description: # optional
# OpsGenie
x-cortex-oncall:
opsgenie:
type: SCHEDULE
id: <SCHEDULE_ID> # Optionally, can use the Rotation UUID instead
x-cortex-owners:
- type: group
name: <GROUP_NAME>
provider: OPSGENIE
description: # optional
x-cortex-alerts:
- type: opsgenie
tag: <KEY>
value: <VALUE>
# PagerDuty
x-cortex-oncall:
pagerduty:
id: <SERVICE_ID> # Service ID
type: SERVICE
x-cortex-oncall:
pagerduty:
id: <SCHEDULE_ID> # Schedule ID
type: SCHEDULE
x-cortex-oncall:
pagerduty:
id: <POLICY_ID> # Escalation Policy ID
type: ESCALATION_POLICY
# Prometheus
x-cortex-slos:
prometheus:
- errorQuery: <query>
totalQuery: <query>
slo: <slo target number>
alias: my-prometheus-instance
name: my-slo-name
# Rollbar
x-cortex-rollbar:
project: <PROJECT_NAME> # projectName in Rollbar
# Rootly
x-cortex-rootly:
services:
- id: ASDF1234
- slug: service-slug
# Sentry
x-cortex-sentry:
projects:
- name: my-project # projectName in Sentry
- name: my-second-project
# Semgrep
x-cortex-semgrep:
projects:
- alias: my_org
projectId: 1234567
- alias: other_org
projectId: 7654321
# ServiceNow
x-cortex-servicenow:
services:
- tableName: cortex-services
id: 1
x-cortex-owners:
- type: group
name: My ServiceNow Team
provider: SERVICE_NOW
description: This is a description for this owner # optional
# Slack
x-cortex-slack:
channels:
- id: ABCDEF123
notificationsEnabled: true
description: This is a description for this Slack channel
- name: team-engineering
notificationsEnabled: true
description: A description for this Slack channel.
# Snyk
x-cortex-snyk:
projects:
- organizationId:<ORGANIZATION_ID>
projectId: <PROJECT_ID>
source: CODE
# SonarQube
x-cortex-static-analysis:
sonarqube:
project: <PROJECT_KEY> # projectKey in SonarQube
alias: sonarqube-alias
# Splunk Observability Cloud (SignalFX)
x-cortex-slos:
signalfx:
- query: <FULL_SFX_QUERY> # Ex. sf_metric:"jvm.memory.max" AND area:"nonheap"
rollup: <ROLLUP>
target: <TARGET>
lookback: <LOOKBACK>
operation: <OPERATION>
# Splunk On-Call (VictorOps)
x-cortex-oncall:
victorops:
type: SCHEDULE
id: <SCHEDULE_ID>
# Sumo Logic
x-cortex-slos:
sumologic:
- id: 000000000001234
- id: 000000000006789
# Veracode
x-cortex-static-analysis:
veracode:
applicationNames:
- My Application
- Second Application
sandboxes:
- applicationName: My Application
sandboxName: My Sandbox
- applicationName: Second Application
sandboxName: Second Sandbox
# Wiz
x-cortex-wiz:
projects:
- projectId: 01234567-e65f-4b7b-a8b1-5b642894ec37
# Workday
x-cortex-owners:
- type: group
name: workday-team-tag
provider: CORTEX
description: This is a description for this owner.
# xMatters
x-cortex-oncall:
xmatters:
id: engineering_group
type: SERVICE
or by email address.
inheritance: When creating a domain entity and adding owners to it, or while creating an entity relationship, you can set ownership inheritance under this block to pass down to the entity's children. The inheritance type can be APPEND, FALLBACK, or NONE.
You will need the Client ID and Azure Tenant ID associated with this app registration.
When you create an app registration, a Service Principal user is also generated.
In your Azure portal, create a Client Secret for your app registration.
While viewing the overview of your app registration, click the link next to "Client credentials." You will be directed to the Certificates & secrets page, where you can click +New client secret to create a secret.
Step 1: Add your Service Principal to your Azure DevOps organization
You must add the Service Principal user to the organization you're integrating with Cortex.
In Azure DevOps, from the list of organizations, select the one you will be integrating with Cortex.
Navigate to Organization Settings > General > Microsoft Entra. Connect your Entra ID directory (the one containing the app registration) with the Azure DevOps organization.
Navigate to Organization Settings > General > Users, then click Add users.
Step 2: Configure the Azure DevOps integration in Cortex
In Cortex, navigate to the .
Click Integrations from the main nav. Search for and select Azure DevOps.
Click Add configuration and select Service Principal.
If the entity is in a monorepo (e.g. in a subdirectory), use this field to define the subdir
alias
Alias for the configuration in Cortex (only needed if you have opted into multi-account support)
List of WIQL conditions to filter work items fetched
alias
Alias for the configuration in Cortex (only needed if you have opted into multi-account support)
The project name as listed under the "Projects" tab when you are logged into Azure DevOps (on the https://dev.azure.com// screen)
✓
alias
Alias for the configuration in Cortex (only needed if you have opted into multi-account support)
pipelines:id
The Azure DevOps system.definitionID for the pipeline.
✓
Name: Enter a name for the configuration.
Project: Select from the dropdown.
Options available in the dropdown are pulled in from the specific Azure DevOps instances configured in Settings.
Select the Work item type and the Sub-item Type from the respective dropdowns. Then, select how the sub-items's fields should be populated on issue creation and status change.
Choose to include or exclude groups of entities, or define a more advanced filter.
.NET (C#): packages.lock.json
Java: pom.xml
Go: go.sum
Weekly PRs merged
Avg PRs reviewed/week
Avg commits per PR
By having a rigorous PR process in place for a repo, you can make sure changes aren't made that create vulnerabilities. This kind of rule could also be used in a best practices or project standards Scorecard.
You can also use a similar expression in the Query Builder to find entities lacking approval:
Name
Definition:git.branches(): List<GitBranch>
Example
For a development best practices Scorecard, you can make sure that branches associated with an entity match a standard naming convention:
Because vulnerabilities in the default branch are critical, this rule should be in one of the first couple levels. A higher-level rule might make sure that branch protection checks are set:
You can also use the Query Builder to find entities with unprotected default branches:
expression in a security Scorecard to make sure entities have fewer than three commits to a "security-fixes" branch in the last week:
Entities passing this rule will include those that haven't needed three or more security fixes. This can indicate that there aren't vulnerabilities in a given entity's code, but could also suggest that fixes aren't being implemented.
Using this rule in conjunction with one focused on vulnerabilities could provide the extra context needed to gain a better understanding of what's happening.
Examples
For a Scorecard focused on development maturity, you could use the git.fileContents() rule to enforce that a CI pipeline exists, and that there is a testing step defined in the pipeline:
A best practices Scorecard, meanwhile, could use this expression for a number of rules:
To make sure node engine version in specified in the package.json file:
To make sure TypeScript projects have a tsconfig.json file checked in:
To make sure projects using yarn do not allow NPM:
And to ensure the yarn version being used is not deprecated:
Or to find entities with an outdated Terraform version:
For a best practices Scorecard, you can also use this expression to make sure the entity's last commit message follows conventional commit guidelines:
This expression can be used in a development maturity Scorecard to write a rule making sure at least 95% of build runs are successful:
As counterintuitive as it may seem, services that are committed too infrequently are actually at more risk. People who are familiar with the service may leave a team, institutional knowledge accumulates, and from a technical standpoint, the service may be running outdated versions of your platform tooling.
Review date
Reviewer
Definition:git.reviews()
Examples
A development maturity Scorecard might use the git.reviews() expression to make sure that there is a rigorous review process in place before changes are implemented:
This rule makes sure that there are more than 25 reviews left in the last week.
You can use the git.codeSearch() expression to query for entities that have certain components, like icons:
project
The name of the project as listed under the "Projects" tab when you are logged into Azure DevOps (on the https://dev.azure.com// screen)
✓
repository
The repo name you see when you navigate to the "Repos" section of Azure DevOps
✓
projects
List of the projects
✓
name
The project name as listed under the "Projects" tab when you are logged into Azure DevOps (on the https://dev.azure.com// screen)
SELECT
[System.Id],
[System.AssignedTo],
[System.State],
[System.Title],
[System.Tags]
FROM workitems
WHERE
'[System.TeamProject] = Design Agile'
AND '[System.WorkItemType] = User Story'
AND '[System.State] = Active'
ORDER BY [System.ChangedDate] DESC
ASOF '02-11-2020'
git.fileContents(“circleci/config.yml”).matches(“.*npm test.*”) - Enforce that a CI pipeline exists, and there is a testing step defined in the pipeline
git.fileExists(*Test.java”)
git.fileExists("terraform/versions.tf") and !git.fileContents("terraform/versions.tf").matchesIn("required_version =! \"[~>= ]{0,3}0\\.(12|13)")
Host: Optionally, if you are using a self-managed setup, enter your hostname.
In the side panel, configure the new user:
Users or Service Principals: Enter the Service Principal associated with your app registration.
Access level: Select Basic.
Add to projects: Add the user to the project(s) that your Cortex integration will need access to.
Azure DevOps Groups: Select security groups. Project Contributors should be sufficient, or you can choose a custom security group that has Code write permissions.
Learn more about .
At the bottom of the side panel, click Add.
Configure the Azure DevOps integration form:
Category: Select which integration categories this configuration will apply to.
Configuration alias: Enter an alias for this configuration.
Organization: Enter the slug for your Azure DevOps organization.
Client ID: Enter the Application Client ID for your app registration.
Client Secret: Enter the Client Secret for your app registration.
Azure Tenant ID: Enter the Directory (Tenant) ID for your app registration.
Host: Optionally, if you are using a self-managed setup, enter your hostname.
GitHub is a Git-based source code repository. You can use GitHub to share code with team members, track and manage changes to code over time, and collaborate on projects across your organization.
Integrating GitHub with Cortex allows you to:
Automatically discover and track ownership of GitHub entities
Follow a GitOps workflow with GitHub to manage your Cortex workspace
View information about your GitHub repositories on an , including: The repo associated with the entity, recent commits and releases in the event timeline, the most-used language in the files for that entity, the top code contributors, and their number of contributions.
In an entity's Code & Security section, see vulnerabilities from (Code scanning, Dependabot alerts, CodeQL, and Secret scanning)
View information about pull requests and work items in the
Use GitHub metrics in to understand key metrics and gain insight into services, incident response, and more
Create that track progress and drive alignment on projects involving your repositories
You can also optionally integrate GitHub Copilot with Cortex to:
Track Copilot adoption and impact within
GitHub Copilot integration
If you installed the GitHub app prior to October 14, 2025, you must accept new permissions in order to access Copilot metrics in Cortex. for more information.
How to configure GitHub with Cortex
Prerequisites
If you connect Cortex via a , it must be configured with a token containing the minimum permissions listed below.
Note: The is preconfigured with these permissions.
Repository permissions
Organization-level permissions
Permission
Requirement
Purpose in Cortex
Choose a configuration option
There are multiple options for connecting Cortex to your GitHub instance:
Through Cortex's official GitHub app
Note: This is supported for use with a single organization in GitHub.
Through a custom GitHub app
If your GitHub setup involves multiple organizations, you can add multiple GitHub apps, use a that has access to all orgs, or create multiple configurations with corresponding aliases.
See the tabs below for instructions on each of the GitHub integration options.
If you're using a self-hosted instance of GitHub, you'll need to verify that your Cortex instance is able to reach the GitHub instance. We route our requests through a static IP address.
Reach out to support at to receive details about our static IP. If you're unable to directly allowlist our static IP, you can route requests through a secondary proxy in your network that has this IP allowlisted and have that proxy route traffic to your GitHub instance.
Configure GitHub with the Cortex GitHub app
is the easiest way to connect your GitHub instance. It is preconfigured with the needed to use this integration. Note that it is not available for Cortex Server.
To set up the app:
In Cortex, navigate to the :
Configure the integration for multiple GitHub accounts
The GitHub integration has multi-account support. You can add a configuration for each additional organization, instance, or account by repeating the process above.
Each configuration requires an alias, which Cortex uses to correlate the designated organization, instance, or account with registrations for various entities. Registrations can also use a default configuration without a listed alias. You can edit aliases and default configurations from the GitHub page in your Cortex settings. Select the edit icon next to a given configuration and toggle Set as default on. If you only have one configuration, it will automatically be set as the default.
Cortex supports mapping multiple identities for a single user if you have multiple configurations of GitHub. See the for more information.
To write rules related to Dependabot alerts, you must verify the necessary permissions are set for repositories you'd like to see vulnerabilities reported on.
To verify, navigate to a repository on GitHub and click "Settings" → "Code security and analysis". Make sure you are a member of a team under "Access to alerts.
Registration
See the for instructions on importing entities.
Entity descriptor
Repository
You can define a GitHub repository for a given entity by adding the x-cortex-git block to the entity's descriptor. When you define a repository, Cortex checks for Security Advisory vulnerabilities from the GraphQL API and Advanced Security vulnerabilities from the Rest API.
Field
Description
Required
Only one repository can be defined for in a given entity's YAML in the x-cortex-git block. Users looking to list additional repositories without the full functionality of GitOps can define the repos as custom data.
Ownership
You can define the following block in your Cortex entity descriptor to add your GitHub teams. Be sure to include both your GitHub organization name and the team name in the name field.
Field
Description
Required
Multiple GitHub organizations are not supported for ownership, and Cortex will use the default configuration when fetching teams.
Identity mappings
Cortex maps users' email addresses to discovered GitHub accounts, so you never need to define email ownership in an entity descriptor. Users must be members of GitHub teams to be pulled in to Cortex.
You can confirm users' GitHub accounts are connected from .
Using the GitHub integration
View GitHub data on entity pages in Cortex
The GitHub integration will populate the Repo and Language detail blocks on an . If a GitHub team has been for an entity, it will also appear in the Owners block.
Code & security
Vulnerabilities appear in the Vulnerabilities block under Code & security on an entity page overview.
Click Code & security in an entity's sidebar to view the full list of vulnerabilities for an entity. Cortex checks for:
Security Advisory vulnerabilities from the GraphQL API
vulnerabilities
Cortex pulls data from code scanning, Dependabot alerts, CodeQL, and Secret scanning.
GitHub Advanced Security vulnerabilities are not surfaced for monorepos.
You can query for vulnerabilities with CQL and create Scorecard rules based on security metrics. See below.
Events
Recent commits appear at the top of an entity's overview page.
You can also click Events in the entity's sidebar to see all commits and releases associated with that entity. Each is hyperlinked to the commit or release page in GitHub and includes a timestamp.
Repository
You can access more detailed information pulled from GitHub in the Repository page in the sidebar. At the top of the page, you'll find the repo(s) associated with that entity and the most-used language in files for that entity. In the Top contributors block, you'll find the three users who have contributed the most code and the number of their contributions.
In the Commits section, you'll find the 10 most recent commits and metadata about each. Below Commits is the Recent releases section, which includes the 5 most recent releases.
Issue tracking
From the Issue tracking page in the entity's sidebar, you can find a list of open . Each issue will show the number, title, assignees, and date created.
Packages
Packages are automatically scraped from your Git repos or they can be submitted via the . The package file must be in the root of your repository — or, if you're using basepath, in the root of the subdirectory — to be scraped by Cortex. You can query an entity's packages in using packages().
To view packages, click Packages in the entity's sidebar.
The following package types are automatically scraped from repositories:
All other files of these types can be added via the .
CI/CD - GitHub workflows
From the CI/CD > GitHub workflows page in the entity's sidebar, you can find a history of runs for the past week. Each run is tagged with its status: IN_PROGRESS, COMPLETED, SUCCESS, CANCELLED, FAILURE, PAUSED.
The GitHub workflows page displays data about workflows in GitHub, not Workflows initiated via .
Team entity pages
When a with a team entity, Cortex will pull GitHub users in to the Members tab. When available, Cortex will pull in the profile picture and email address for each user.
Engineering homepage
The GitHub integration enables Cortex to pull information about pull requests and issues into the . You can find your open pull requests, any pull requests assigned to you for review, and any issues assigned to you.
Pull requests and issues from GitHub are refreshed every 2 minutes.
Eng Intelligence
The uses pull request data from GitHub to generate metrics:
Average PR open to close time
Avg time to first review
Avg time to approval
PRs opened
Eng Intelligence also pulls in data from Copilot to show AI impact in the .
You can read more about how Eng Intelligence tracks metrics for teams and users in the .
To add deployments for your Github related entity, you can send a deployment event to the
Scorecards and CQL
With the GitHub integration, you can create Scorecard rules and write CQL queries based on GitHub data.
See more examples in the in Cortex.
Approvals required to merge
Number of approvals required to merge a pull/merge request into a repository. Defaults to 0 if no approvals are defined.
Definition: git.numOfRequiredApprovals()
Examples
For a security or development maturity Scorecard, you can write a rule to make sure at least one approval is required to merge a pull/merge request:
Git repository set
Check if an entity has a registered Git repository.
Definition:git (==/!=) null: Boolean
Example
In a Scorecard, you can write a rule that detects whether an entity has a Git repository set:
Branches
List all live branches with some basic metadata.
Head
Is protected
Branch protection details
Find details for specified branch, or default branch if none is specified.
Branch name
Code owner reviews required
Commits
Get the latest commits (to a maximum of 100) for a defined lookback period (defaulting to 7 days).
Date
Message
Default branch
Default branch for the repository, or main when null.
Definition:git.defaultBranch()
Example
If default branches should always be named "main," you can write a rule to make sure entities follow this practice:
File contents
Load the contents of a file from the entity's associated repository.
The contents can be validated by using string comparison operations or parsed by the built-in jq function. The jq function will automatically coerce file contents of JSON or YAML formats.
Definition:git.fileContents()
Example
For a Scorecard focused on development maturity, you could use the
File exists
Check if file exists from within the entity's associated repository.
Definition:git.fileExists()
Examples
For a Scorecard focused on best practices, you can make sure that repositories contain a README.md file:
This rule would make sense in the first level because it's so essential.
Number of Git vulnerabilities
Check the number of vulnerabilities for an entity's associated repository.
You can filter by severity (by default searches by all severities) or source (by default only searches GitHub security advisories).
When using the GitHub Advanced Security source, severities displayed in the UI may not match severities returned by the API.
Definition:git.numOfVulnerabilities()
List of Git vulnerabilities
Lists the vulnerabilities for an entity's associated repository. You can filter by severity (by default searches by all severities) or source (by default only searches GitHub security advisories). Note when using the GitHub Advanced Security source, severities displayed in the UI may not match severities returned by the API.
Definition: git.vulnerabilities()
Examples
You could write a Scorecard rule that verifies an entity has fewer than 5 Git vulnerabilities:
Has Cortex YAML
Check if a repository has a valid cortex.yaml file checked in at the root directory (when GitOps is enabled).
Definition:git.hasCortexYaml()
Example
If you're using a Scorecard to track a migration from Cortex UI to GitOps, you can use this rule to make sure entities are set up for GitOps management of entity descriptors:
Last commit details
Provides last commit details.
Date
Message
Pull requests
Lists pull requests opened during a defined lookback period.
Approval date
Author
Reviews
List reviews left during a defined lookback period.
Organization
Repository
Workflow runs
Get workflow runs meeting given filter criteria, including conclusions, statuses, and a lookback period.
Conclusion
Name
Ownership CQL
All ownership details
A special built-in type that supports a null check or a count check, used to enforce ownership of entities.
Definition:ownership: Ownership | Null
Example
An initial level in a security Scorecard might include a rule to ensure an entity has at least one team as an owner:
All owner details
List of owners, including team members and individual users, for each entity
Definition:ownership.allOwners()
Example
The Scorecard might include a rule to ensure that entity owners all have an email set:
Team details
List of teams for each entity
Definition:ownership.teams(): List<Team>
Example
The Scorecard might include a rule to ensure that an entity owners all have a description and are not archived:
Copilot CQL
AI adoption
The ratio of licensed seats that were active users of AI coding tools in a given time period. Returns a value between 0 and 1, where 1 represents 100% adoption. Note: This metric is only available for Team entities.
You could create a Scorecard rule to verify you had at least 5 active AI users in the last 7 days:
External repositories
By default, each GitHub rule is evaluated on the repository defined in a given entity descriptor. If the base path parameter has been set, CQL rules will automatically scope to the base path subdirectory.
To evaluate the rule for a service for an external repository, pass the repo identifier in the git(repoIdentifier: Text) command (e.g. git("github:org/repositoryName")).
This can be combined with other CQL rules. For example, a rule based on a dynamic external repository with custom data would be git("github:" + custom("my-custom-repo")).fileExists("README.md").
View integration logs
This feature is available to Cortex cloud customers.
On the integration settings page, click the Logs tab to view logs from the last 7 days. Learn more in .
Background sync
Cortex conducts a background sync of GitHub identities every day at 10 a.m. UTC. Pull requests and issues are refreshed about every 10 minutes.
FAQs and troubleshooting
I'm getting this error: "{"message":"Not Found", "documentation_url":"https://docs.github.com/rest/repos#get-a-repository"}".
If you've set up multiple GitHub accounts/organizations, Cortex will not be able to identify the correct one unless the alias variable is defined.
What if I have multiple email addresses set in my GitHub account?
Cortex will only detect the primary email address associated with your GitHub account if it is public.
If Cortex is not correctly pulling in user emails, ensure the given user(s) have allowed their email address to be public. Make sure the "Keep my email address private" setting is unchecked in the user's personal GitHub settings.
My ownership isn't being automatically mapped through GitHub.
If the email address associated with your Cortex account is not the same as your GitHub email address, you need to add your Cortex email address to the Public email dropdown in GitHub settings.
Github OAuth, which you can configure in Cortex user settings, allows you to link your GitHub username with your Cortex account, even if you don't have a public email set up on GitHub.
Still need help?
The following options are available to get assistance from the Cortex Customer Engineering team:
Email: , or open a support ticket in the in app Resource Center
Slack: Users with a connected Slack channel will have a workflow added to their account. From here, you can either @CortexTechnicalSupport or add a :ticket: reaction to a question in Slack, and the team will respond directly.
Don’t have a Slack channel? Talk with your Customer Success Manager.
Read & write
Used to create and update check runs for linting and validation workflows, such as the cortex.yaml linter on pull requests.
Code scanning alerts
Read-only
Get vulnerability information for Git-based CQL rules
Commit statuses
Read & write
Read commits for an entity's Git metadata
Read commits for Git-based CQL rules
Show pending status messages on the OpenAPI incompatibility check
Contents
Read & write
Read cortex.yaml, cortex-properties.yaml, and package/OpenAPI files
Read Git rules
Create file contents
Custom properties
Read & write
Used in
Dependabot alerts
Read-only
Read vulnerability information for Git CQL rules (only relevant if using Dependabot)
Deployments
Read & write
Used in
Issues
Read & write
Read associated issues with repositories for populating entity Git integration and for Git CQL rules
Create new issues based on
Metadata
Read-only
Read associated data with repositories for populating entity Git integration and for Git CQL rules
Pull requests
Read & write
Read pull request data for Git CQL rules and developer homepage "My PRs" tab
Comment if there are breaking OpenAPI changes on a PR
Secret scanning alerts
Read-only
Read vulnerability information for Secret scanning
Secrets
Read & write
Optionally write repo secrets after creating new repo
Single file
Read & write (path to cortex.yaml)
Read cortex.yaml files
Create cortex.yaml files
Workflows
Read & write
Write in GitHub actions files
Read-only
Read copilot related metrics for AI Impact Dashboard
By using Cortex's official GitHub app or a custom GitHub app, users can tag entities with Git details and enable GitOps-style configuration of data in Cortex.
Using a personal access token
Using Cortex Axon Relay, a relay broker that allows you to securely connect your on-premises GitHub data.
Click Integrations from the main nav. Search for and select GitHub.
On the GitHub settings page, next to cortex, click Install.
Follow the prompts, then click Install & Authorize.
Support for using GitHub teams as an ownership provider.
The app comes with a built-in linter, which validates the format of a given cortex.yaml file and checks Cortex-specific items. However, the linter DOES NOT validate data correctness. For example, the linter will confirm that the format of a group block is correct, but will not check that the group exists.
Configure GitHub with a custom app
If you're using Cortex Server, or if you don't want to use the official Cortex app, you can connect a custom GitHub app.
Make sure you have configured the permissions listed above under Prerequisites.
Step 1: Register the custom app in GitHub
Register the app. When you're creating the app, make sure to follow these steps:
Disable "Expire user authorization tokens." (Cortex does not support this OAuth workflow yet.)
Select "Request user authorization (OAuth) during installation."
Add a webhook secret of your choosing that will be identical to the webhook secret token configured later in Cortex settings.
Set the repository and organization outlined in the configuration modal.
CheckPush and Check suite under Subscribe to events.
After the app has been created, generate a client secret and private key.
Step 2: Configure the custom app in Cortex
In Cortex, navigate to the :
Click Integrations from the main nav. Search for and select GitHub.
Click Add configuration, then for the type, select GitHub app.
Configure GitHub with a personal access token
Prerequisites
Before getting started, make sure your personal access token has, at minimum, the repo and read:org permissions.
Note: Beyond the minimum permissions indicated above, many scenarios will require that the user who generated the personal access token have organization ownership permissions within GitHub.
Configuration
In Cortex, navigate to the :
Click Integrations from the main nav. Search for and select GitHub.
Click Add configuration.
In the upper right corner of the modal, click the dropdown and select Personal access token.
Fill in the form:
Alias: Enter a name that Cortex will associate with a given configuration.
Token: Enter the Personal access token generated in GitHub.
Click Save.
Configure GitHub with Cortex Axon Relay
See Internally hosted integrations for instructions. Make sure to follow the GitHub-specific instructions for the docker-compose.yml file.
Alias for the configuration in Cortex (only needed if you have opted into multi-account support)
Name of integration (in this case, GITHUB)
✓
description
Description for the GitHub team
Dependency reviews are not supported.
.NET (C#): packages.lock.json
Java: pom.xml
Go: go.sum
Weekly PRs merged
Avg PRs reviewed/week
Avg commits per PR
Ave lines of code changed per PR
By having a rigorous PR process in place for a repo, you can make sure changes aren't made that create vulnerabilities. This kind of rule could also be used in a best practices or project standards Scorecard.
You can also use a similar expression in the Query Builder to find entities lacking approval:
Name
Definition: git.branches()
Example
For a best practices Scorecard, you can make sure that branches associated with an entity match a standard naming convention:
Dismiss stale reviews
Required status checks
Restrictions apply to admin
Review required
Definition:git.branchProtection()
Examples
For a security Scorecard, you can write a rule to make sure the default branch is protected:
Because vulnerabilities in the default branch are critical, this rule should be in one of the first couple levels.
You can also use the Query Builder to find entities with unprotected default branches:
SHA
URL
Username
These results can be filtered based on branch name, using the default branch if no other branch is provided.
Definition:git.commits()
Example
You can use the git.commits() expression in a security Scorecard to make sure entities have fewer than three commits to a "security-fixes" branch in the last week:
Entities passing this rule will include those that haven't needed three or more security fixes. This can indicate that there aren't vulnerabilities in a given entity's code, but could also suggest that fixes aren't being implemented. Using this rule in conjunction with one focused on vulnerabilities could provide the extra context needed to gain a better understanding of what's happening.
git.fileContents()
rule to enforce that a CI pipeline exists, and that there is a testing step defined in the pipeline.
A best practices Scorecard, meanwhile, could use this expression for a number of rules:
To make sure node engine version in specified in the package.json file:
To make sure TypeScript projects have a tsconfig.json file checked in:
To make sure projects using yarn do not allow NPM:
And to ensure the yarn version being used is not deprecated:
A higher-level rule in a best practices Scorecard might confirm that developers are checking in lockfiles to ensure consistency in package installs:
And/or a rule that makes sure there are unit tests enabled:
Finally, you could write a rule to make sure projects have a standard linter:
Examples
A security-focused Scorecard will likely include a rule making sure there are no Git vulnerabilities:
You can use Scorecard levels to stratify vulnerabilities by risk. An initial level might make sure there are no critical vulnerabilities:
While a higher level might make sure there are no vulnerability warnings:
You could write a rule that verifies the entity has no vulnerabilities with "High" or "Critical" severity sourced from GitHub Advanced Security:
SHA
URL
Username
Definition:git.lastCommit()
Examples
One of the first rules you might write for a Scorecard focused on development maturity or security is one validating that the last commit was within the last month:
As counterintuitive as it may seem, services that are committed too infrequently are actually at more risk. People who are familiar with the service may leave a team, institutional knowledge accumulates, and from a technical standpoint, the service may be running outdated versions of your platform tooling.
Depending on best practices at your organization, you may want to confirm entities are updated within a week:
Confirming whether a service was updated within the last week can help team members catch outdated code sooner. Plus, if there is a security issue, you can quickly determine which services have or have not been updated to patch the vulnerability.
Date closed
Date opened
First review date
Last updated
Number of commits
Number of lines added
Number of lines deleted
Organization
Repository
Source
Status
URL
Definition:git.pullRequests()
Example
You can use the git.pullRequests() query to find entities that have a small number of pull requests opened in the last two weeks:
This can highlight entities that haven't been updated recently, which may be especially useful when entities have to be updated to address a vulnerability.
Review date
Reviewer
Definition:git.reviews()
Examples
A development maturity Scorecard might use the git.reviews() expression to make sure that there is a rigorous review process in place before changes are implemented:
This rule makes sure that there are more than 25 reviews left in the last week.
Run started at
Run time
Run updated at
Status
Conclusions: FAILURE, SUCCESS, TIMED_OUT
Statuses: QUEUED, IN_PROGRESS, COMPLETED
The lookback period specifies a duration for which returned runs should be created within, defaulting to a period of 3 days.
The runTime of the WorkflowRun object represents the difference between runStartedAt and runUpdatedAt times in seconds.
Definition:git.workflowRuns()
Example
To make sure an entity has had a successful workflow run within the last two weeks, you can write a rule like:
This rule is checking for GitHub workflow runs with a SUCCESS conclusion and COMPLETED status during a 14-day lookback window.\
To find the percentage of successes in workflow runs, you could write a query similar to:
Permission
Requirement
Purpose(s) in Cortex
Actions
Read & write
Read workflow run information for Git-based CQL rules
Subdirectory for the entity if it is in a monorepo. Note that setting a basepath filters the vulnerabilities that appear in Cortex; Advanced Security vulnerabilities will not appear.
type
Ownership type; must be defined as group for GitHub teams
✓
name
GitHub team name in the form /Team names are generally converted to lowercase with - separators (Team Name would be cortex/team-name), but you can verify your exact name from the GitHub permalink
x-cortex-owners:
- type: group
name: cortex/engineering
provider: GITHUB
description: This is a description for this GitHub team that owns this entity.
Alias: Enter the name Cortex will associate with a given configuration.
Application ID: Enter the ID for your custom GitHub ap.
Client ID: Enter the unique client ID assigned to your app during registration.
Client secret: Enter the unique client secret assigned to your app during registration.
Private key: Enter the to authenticate with your GitHub app.
Public link: Enter the public URL of your GitHub app.
API endpoint (for GitHub enterprise): Enter the endpoint root URL for self-managed GitHub setups.
Click Save.
On the GitHub Settings page in Cortex, under Webhook, choose your new configuration alias and enter the same Secret token that was entered in GitHub during the app configuration.
On the GitHub Settings page in Cortex, next to your custom app configuration's name, click Install.
API endpoint (for GitHub enterprise): Enter the endpoint root URL for self-managed GitHub setups.
