> For the complete documentation index, see [llms.txt](https://docs.cortex.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cortex.io/solutions/ai-governance.md). # AI governance Engineering teams need to ship quickly without creating compliance or reputational risks. AI governance is the set of processes, policies, and oversight mechanisms that ensure your AI systems are developed, deployed, and used responsibly. **How Cortex helps with AI governance** Your organization can drive AI governance with Cortex by: * Tracking all AI and ML services across your organization with a single source of truth for what models exist, who owns them, and which compliance checks they've passed * Using Scorecards to encode governance standards, covering PR review requirements, automated security testing in CI/CD, incident response plans, and MITRE ATLAS compliance checks * Configuring Workflows to enforce governance at the point of creation, scaffolding new AI services with required security configs, data privacy policies, and vendor risk assessments by default * Using Cortex MCP to get instant answers about compliance status, ownership, and Scorecard progress directly from your editor * Reviewing Eng Intelligence metrics to track whether AI initiatives are improving engineering efficiency without introducing reliability risk
## Step 1: Ingesting data and establishing ownership For AI governance to work, you need clear visibility into what you're governing. Start by importing your services, resources, infrastructure, and other entities into Cortex and ensuring ownership is assigned. This establishes a single source of truth across your engineering organization and unlocks the rest of the platform: Scorecard tracking, Workflow automation, MCP queries, and Eng Intelligence reporting. In addition to Cortex's built-in entity types, you can create custom entity types to represent AI-specific entities. For example, creating a type called "AI Models" lets you categorize and govern models separately from other services. {% hint style="info" %} It's recommended to add a group called `ai-enabled` to your AI-enabled services. This makes it easy to filter them in the relationship graph, Scorecards, and anywhere else in Cortex that supports filters. {% endhint %} ### What to do [Import your services, infrastructure, and other entities](/ingesting-data-into-cortex/overview.md) into Cortex. [Assign an owner](/ingesting-data-into-cortex/entities-overview/entities/ownership.md) (team or individual) to each entity. Then [connect the integrations](/ingesting-data-into-cortex/integrations.md) that give Cortex visibility into how those entities are built, tested, and deployed. For AI-specific entities like models or pipelines, consider creating a [custom entity type](/ingesting-data-into-cortex/entities-overview/entities/adding-entities/entity-types/creating-custom-entities.md) to group and track them separately. ### **Integrations to prioritize** To govern AI systems effectively, you need visibility and control across code, CI/CD, project management, observability, and documentation. Make sure you have integrations configured for:
CategoryTools
Version controlAzure DevOps, Bitbucket, GitHub, GitLab
Project managementGitHub, Jira, Azure DevOps, ClickUp
CI/CDArgoCD, Azure DevOps, Bitbucket, Buildkite, CircleCI, GitHub, GitLab, Jenkins
ObservabilityCoralogix, Datadog, Dynatrace, Google Observability Cloud, New Relic, Prometheus, Splunk Observability Cloud
DocumentationLink runbooks and documentation to your entities so teams have access to compliance docs for AI usage. You can use Scorecards to verify this is in place.
{% hint style="success" %} #### You'll know this step is done when... Your entities are visible in the Cortex catalog, every AI-related service and resource has an owner assigned (no unowned entities), your integrations are connected and actively pulling data (not just authenticated, but actually returning signals), and the `ai-enabled` group tag is applied to the right services.
A quick check: try filtering by the `ai-enabled` group in the relationship graph and confirm the list looks correct. {% endhint %} ### Common issues * **Integrations not returning data** - This is usually a scope or permissions problem on the integration side. Double-check that the credentials or tokens you used have read access to the repos, pipelines, or tools you're trying to pull from. * **Ownership gaps** - Teams often connect their services but skip assigning owners, which means Scorecards can't route failing rules to anyone and Initiatives have no one to notify. Run an ownership report early and resolve gaps before moving to [Step 2](#step-2-creating-an-ai-governance-scorecard). * **Missing services** - if you're ingesting via a catalog descriptor file (like `cortex.yaml`), repos without one won't appear. Either add descriptor files or use an integration-based ingestion method that picks up services automatically. * **Skipping the MITRE ATLAS custom data field** - If you skip creating it before activating the Scorecard in [Step 2](#step-2-creating-an-ai-governance-scorecard), the rule that depends on it will error rather than just fail, which looks confusing. Create the field first. ## Step 2: Creating an AI governance Scorecard [Scorecards](/standardize/scorecards.md) automate the process of checking whether services meet your AI governance standards. Cortex's AI governance Scorecard template includes predefined rules organized into three levels (Bronze, Silver, and Gold), each representing increasing levels of governance maturity. The template checks for industry best practices such as PR reviews required from codeowners, automated security testing in CI/CD, and incident response plans for AI security. You can reorder, delete, and edit rules, add new ones to any level, and weight rules by importance using point values. ### **Prerequisites** One rule in the template requires a custom data field to track whether entity owners have reviewed the [ATLAS Matrix](https://atlas.mitre.org/matrices/ATLAS). Before using that rule, create a custom data field named `owners-reviewed-mitre-atlas-matrix`. ### What to do [Create a Scorecard](/standardize/scorecards/create.md#create-scorecard-from-template) using the AI governance template. {% hint style="success" %} #### You'll know this step is done when... The Scorecard is created from the AI governance template, scoped to your `ai-enabled` services, and actively evaluating. You can open the Scorecard evaluate view and see actual pass/fail results for your services across Bronze, Silver, and Gold, not blank rows or errors. Some rules will be failing at this point; that's expected. What you don't want to see is rules returning "N/A" or erroring out, which usually signals a configuration problem. {% endhint %} ### Common issues * **Rules returning "N/A"** - This typically means the rule's CQL query references an integration you haven't connected yet, or the entity doesn't have the relevant data. Go back to [Step 1](#step-1-ingesting-data-and-establishing-ownership) and verify the integration is pulling data for those services. * **Template rules that don't match your stack** - The template is built around common industry tools, but if you don't use a specific CI/CD platform or security scanner it references, those rules will always fail or be irrelevant. Review the rules before activating and delete or swap any that don't apply to your environment. * **The Scorecard scoped too broadly or too narrowly** - If you forget to filter by the `ai-enabled` group, you'll be evaluating every service in your catalog against AI governance rules, which creates noise and makes the results harder to act on. Scope it to the right entities before sharing it with teams. * **The MITRE ATLAS rule erroring** - If you didn't create the `owners-reviewed-mitre-atlas-matrix` custom data field before creating the Scorecard, that rule errors rather than failing cleanly. Create the field, then re-evaluate. * **Point weighting not reflecting actual priorities** - The template assigns default weights, but if PR review enforcement is your highest-stakes requirement and it's weighted the same as a lower-priority rule, your Bronze/Silver/Gold thresholds won't reflect real risk. Adjust weights before rolling out to teams so the levels mean something. ## Step 3: Automating processes with Workflows [Workflows](/streamline/workflows.md) let you enforce governance standards before problems can occur, at the moment a new service is created. Use the [Scaffolder](/streamline/workflows/scaffolder.md) to ensure every new AI service starts with baseline governance in place. As a best practice, your Scaffolder template should include files for: * AI service configuration security * AI security documentation and guidelines * Data privacy and PII protection measures * External AI vendor risk assessments * AI model access controls and authentication The AI governance Scorecard template checks for these files, so scaffolding them by default means new services start at a passing baseline rather than accruing immediate debt. ### **Identifying good candidates for Workflow automation** Good candidates share a few traits: they happen repeatedly, skipping them creates compliance or security risk, and they currently rely on people remembering to do them. **In an AI governance context, look for these patterns**: **New service creation** is the highest-value candidate. Every new AI service that gets scaffolded without the right files (security config, data privacy policy, vendor risk assessment, access controls) starts life out of compliance. A Scaffolder Workflow fixes this permanently; governance artifacts are present by default, not retrofitted later. **AI tool access requests** are a good fit when you need a consistent, auditable approval process. If engineers are requesting access to GitHub Copilot or other AI coding tools over Slack or email today, that's a workflow waiting to be automated: request, approval, provisioning, and a record that it happened. **Compliance attestations** that need periodic renewal—like teams confirming they've reviewed the MITRE ATLAS matrix—are good candidates when the frequency is predictable and the main failure mode is people forgetting. A timed Workflow can prompt the right owners, collect responses, and update the relevant custom data field that your Scorecard checks. **Model deployment gates** are worth automating if you need a human review or checklist before an AI model goes to production. If that process is ad hoc today, a Workflow can enforce it consistently across teams. {% hint style="info" %} A quick signal that something isn't a good candidate: if it requires significant human judgment on every instance, a Workflow can facilitate it but won't replace the judgment. Automation works best on the consistent, repeatable parts like routing, reminding, collecting, and scaffolding, not on decisions that genuinely vary case by case. {% endhint %} ### **What to do** Create a [Workflow](/streamline/workflows/create.md), [configure its settings](/streamline/workflows/configuring-workflow-settings.md), and [add blocks](/streamline/workflows/blocks.md). You can create a Workflow based on a template or create one from scratch. {% hint style="success" %} #### You'll know this step is done when... Your Scaffolder template includes all governance files the AI Governance Scorecard checks for, and a new service created through it immediately passes those rules without any manual work from the service owner. For any additional Workflows (access requests, attestations, deployment gates), each one should have at least one successful end-to-end test run before you consider it complete. {% endhint %} ### Common issues * **Scaffolder template missing files the Scorecard checks for** - The Scorecard rules and the Scaffolder template need to stay in sync. If you add a governance rule later without updating the template, new services will immediately fail it. Treat the two as a pair and update them together. * **Teams bypassing the Scaffolder** - If engineers can create services without using the Scaffolder (direct repo creation, cloning an existing service), the governance files never get added. The Scorecard will catch this eventually, but you'll be remediating after the fact. Enforce the Scaffolder as the required path for new AI service creation. * **Templates that are too rigid** - If the scaffolded files are fully locked down, engineers will work around them or file exceptions constantly. Leave room for teams to fill in service-specific details while keeping the governance structure non-negotiable. * **Untested Workflows going live** - Routing errors, misconfigured approvals, and missing notification targets are common on first runs. Test each Workflow end-to-end in a non-production context before rolling out to teams. * **Access request Workflows with no clear SLA** - If you automate the request process but don't set expectations on approval turnaround, engineers will abandon the Workflow and find informal workarounds. Define who approves, and how fast. ## Step 4: Configuring Cortex MCP [Cortex MCP](/get-started/mcp.md) gives engineers conversational access to governance information without leaving their editor. Use it to answer questions about compliance status, ownership, and Scorecard progress in real time. * Ask ***What AI models are currently deployed in our environment?*** to get a live view of your AI service inventory * Ask ***Give me next steps for my AI Governance Scorecard*** to get a prioritized remediation list * Use it to quickly find out which teams are accountable for each model, pipeline, or AI service in your environment ### What to do [Configure the Cortex MCP](/get-started/mcp/configuring-cortex-mcp.md). It can be hosted locally or remotely. Refer to [Using the Cortex MCP](/get-started/mcp/using-cortex-mcp.md) for information on starting a new chat, crafting effective prompts, and using Eng Intelligence metrics in chat. {% hint style="success" %} ### **You'll know this step is done when...** At least one engineer on your team has MCP configured and can successfully query Cortex in natural language from their editor. {% endhint %} ### Common issues * **MCP not connected to the right workspace** - If the MCP is pointed at the wrong Cortex workspace or authenticated with credentials that have limited permissions, queries will return incomplete or no results. Verify the connection returns accurate data for a service you know well before rolling it out. * **Questions that are too vague** - MCP works best with specific, scoped questions. ***How are my AI services doing?*** returns less useful results than ***What are quick wins for my AI Governance Scorecard?*** Train teams on the kinds of questions that get actionable answers. * **Data gaps from Step 1 surfacing here** - MCP can only return what's in Cortex. If ownership isn't set, integrations aren't pulling data, or services are missing from the catalog, queries about those services will return nothing or incomplete answers. Gaps that felt minor in [Step 1](#step-1-ingesting-data-and-establishing-ownership) become visible here. * **Teams not aware it exists** - MCP adoption tends to be low when it's announced once and forgotten. Engineers default to existing habits (Slack, wikis, asking a colleague) unless MCP is introduced in the context of a workflow they already use, like a Scorecard remediation or an incident investigation. ## Step 5: Reviewing Eng Intelligence metrics Use [Eng Intelligence](/improve/eng-intelligence.md) to track whether AI initiatives are improving efficiency without sacrificing reliability. Before rolling out your AI governance Scorecard, pull baseline metrics from the [DORA dashboard](/improve/eng-intelligence/dashboards/dora-dashboard.md), Velocity dashboard, and [Metrics Explorer](/improve/eng-intelligence/metrics-explorer.md). **Key metrics to baseline**: * Cycle time * Incident frequency * Time to resolution ### What to do Analyze metrics in the [Metrics Explorer](/improve/eng-intelligence/metrics-explorer.md), the Cortex [dashboards](/improve/eng-intelligence/dashboards.md), and in [reports](/improve/reports.md). {% hint style="success" %} ### **You'll know this step is done when...** You have baseline metrics captured in Eng Intelligence before your AI governance Scorecard goes live, specifically: cycle time, change failure rate, MTTR, and deployment frequency. You know which teams and services are in scope, and you can filter to them in the Metrics Explorer. The baseline doesn't need to look good; it just needs to exist so you have something to measure against later. {% endhint %} ### Common issues * **No baseline captured before launch** - The most common mistake is activating the Scorecard and Workflows first, then trying to establish a baseline after the fact. You lose the before/after comparison. Pull the baseline first, even if it's rough. * **Metrics not available for AI services** - If your `ai-enabled` group wasn't set up in [Step 1](#step-1-ingesting-data-and-establishing-ownership), you may not be able to filter Eng Intelligence to just your AI services. You'll be looking at org-wide data, which makes it hard to attribute changes to your governance program. * **Choosing the wrong metrics to watch** - Cycle time and deployment frequency matter, but for an AI governance program, change failure rate is often the most telling signal. Teams adopting AI-assisted coding without strong review practices tend to see it climb. If you're not tracking it from the start, you'll miss the early warning. * **Metrics present but no owner for the follow-up** - Eng Intelligence shows you the data, but someone needs to be accountable for reviewing it on a regular cadence and acting on regressions. If that ownership isn't established now, the dashboards go unread. ## Next steps Learn about what ongoing AI governance looks like in [AI governance in action](/solutions/ai-governance/in-action.md). --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.cortex.io/solutions/ai-governance.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.