Quick checklist
- Each entity type has one management method (UI, API, or GitOps), and your GitOps settings match it.
- New entities are created automatically, from discovery, a template, or the workflow that creates the service.
- Descriptor changes are validated before they’re applied.
- Teams sync from an identity provider, Git provider, or HR system, and teams (not individuals) own entities.
- Auto-archival is on, so entities that no longer exist leave the catalog.
- A Scorecard flags incomplete entities, and a recurring data verification period asks owners to confirm their data.
Before you start
1
Decide how each entity type is managed
You can create and update entities in three ways. The UI and API update Cortex directly, whereas GitOps changes go through your Git provider first. Choose one method per entity type.
- Cortex UI - People edit entities directly in Cortex. Best for smaller catalogs or entity types that change rarely.
- Cortex API - Your own scripts and pipelines write descriptors to Cortex through the Catalog entities API. The Cortex CLI and Terraform provider use the API too. Best for large-scale or programmatic updates driven by another system.
- GitOps - Descriptors live as
cortex.yamlfiles in Git, and Cortex processes them when changes are committed. Best when you want review, history, and rollback for catalog changes. See GitOps.
2
Connect your Git provider
Many of the patterns below rely on a GitHub, GitLab, Bitbucket, or Azure DevOps integration. If you use GitOps, see Using GitOps for Cortex for setup steps.
3
Agree on your descriptor conventions
Decide on a naming convention for entity tags (
x-cortex-tag), and which fields every entity should have, such as owners, groups, a parent domain, and links. Remember that an entity’s tag can’t be changed later: changing x-cortex-tag creates a new entity.Step 1: Choose how new entities get into the catalog
Most teams combine more than one approach. Use discovery to catch what already exists, and automation to register new services the moment they’re created.Step 2: Generate descriptors from metadata you already have
If you manage entities with the API or GitOps, don’t write each descriptor by hand. Render descriptors from a template (Jinja2 or similar) filled in from data you already have, like a service registry, a deployment manifest, or repository metadata. The template enforces your conventions, so every entity gets the same tag format, parent domain, groups, owners, and links. With GitOps, teams usually commit the rendered descriptors to a central.cortex/catalog repository. With the API, your pipeline sends the rendered descriptor to the Create or update entity endpoint.
For example, a template might render a descriptor like this:
cortex catalog descriptor -y -t <tag> to print an entity’s descriptor as YAML. You can also use the Retrieve entity descriptor and List entity descriptors API endpoints.
Use rendered YAML only. Cortex can’t process a descriptor that still contains template syntax like {{ variable }}. Render the descriptor in your pipeline, then commit or send the result.
Step 3: Validate descriptors before they merge
How you validate depends on how you manage the entity type.- UI - Cortex validates changes when you save, so no setup is needed.
- API - Before your pipeline writes a change, send the descriptor to the Create or update entity endpoint with
dryRun=true. Cortex validates it and returns any errors or warnings without changing the entity. Only write the change if the dry run passes. - GitOps - Open a pull request for every descriptor change instead of pushing straight to the default branch.
- GitHub - The Cortex GitHub app includes a linter that checks descriptors on pull requests and comments with any issues. In GitOps settings, choose which repositories it runs on and whether warnings fail the check.
- Other Git providers - Add a CI step that calls the Create or update entity endpoint with
dryRun=true. - After a change merges, confirm Cortex processed it on the GitOps logs page. An entry that shows
0 entitiesusually means UI editing is still enabled for that entity type, or the repository isn’t on the GitOps repository allowlist. To check a single descriptor, paste it into the YAML linter under Tools > YAML linter.
Step 4: Register new services where they’re created
Build registration into the process that creates the service, and the catalog stays complete without anyone having to remember.- Trigger on your deployment manifests. This pairs well with the template approach in Step 2. For example, a CI job (like a GitHub Action) that runs when a new production Helm chart, Terraform module, or other deployment manifest lands can render the descriptor from the manifest and repository metadata. With GitOps, the job opens a pull request against your catalog repository. With the API, it sends the descriptor to Cortex directly.
- Use the Scaffolder. When the Scaffolder creates a new service from a template, it can register the service in Cortex at the same time. Turn on Create cortex.yaml in git when creating a new service to commit the descriptor to the new repository; otherwise Cortex adds the entity through the API.
- Wrap it in a Workflow. A Workflow can run the Scaffolder, collect the service name and tag from a form, set custom data, and open tickets for follow-up work. See Standardize new service creation for a complete example. Even if you build your own pipeline, it’s a useful model for the steps to include.
- Use Terraform. If new services are provisioned through Terraform, use the
cortex_catalog_entityresource in the Cortex Terraform provider to create the entity alongside the infrastructure.
Step 5: Keep ownership current
Ownership goes stale faster than any other catalog data, because people change teams and teams reorganize. For a deeper guide, see Ownership best practices.- Assign teams, not people. Team owners survive turnover. Individual owners don’t update when someone leaves.
- Sync teams from the system that already knows your org, such as an identity provider, Git provider, or HR system, instead of maintaining membership by hand.
- Fill gaps with recommendations. The Ownership tool recommends owners for unowned entities. If you manage ownership through GitOps, accepting a recommendation opens a pull request that adds the team to
x-cortex-owners, so your repository stays the source of truth. See Accepting recommendations for GitOps-managed entities. - Replace the owners block when you update owners through the API. Write the full
x-cortex-ownersblock with the current owners instead of appending to it, so former owners don’t pile up. The Create or patch entity endpoint replaces arrays by default; don’t setappendArrays=truefor owner changes. If the entity is managed with GitOps, updatex-cortex-ownersin itscortex.yamlinstead. An API change would be overwritten on the next commit.
Step 6: Retire entities that no longer exist
A catalog full of deleted repositories and torn-down resources is as misleading as one with gaps.- Turn on auto-archival. Auto-archival archives entities automatically when they’re no longer detected in an integration, when their YAML file is deleted, or both. Set the source for each entity type in Settings > Entities.
- Set an auto-deletion policy for short-lived resources. If you ingest resources that come and go often, an auto-deletion policy permanently deletes archived entities after a set time, so they don’t pile up.
- Review entities that aren’t detected anymore. The discovered entities list flags catalog entities that Cortex no longer finds in your integrations, such as AWS resource not detected. Archive or delete them from there.
Changing an entity’s
x-cortex-tag creates a new entity instead of renaming the existing one. To change a tag, archive or delete the old entity, then create the new one.Step 7: Catch drift before it spreads
Automation covers most changes, but not all of them. Build in checks that surface what slipped through.- Review discovered entities on a schedule. Check the discovered entities list regularly for new repositories and resources that haven’t been imported. Ignore the ones you don’t need to track, like test repositories, so the list stays short.
- Score catalog completeness. Create a Scorecard that checks the fields your conventions require, so incomplete entities show up as tasks on their owners’ homepages. Start from the Ownership Verification template in Create a Scorecard, or add a rule like
ownership.teams().length > 0to an existing Scorecard. - Run recurring data verification. A data verification period asks owners to confirm that their entities’ details are still accurate. Schedule one after large imports or reorgs, and on a regular cadence after that. See Data verifications for audit readiness for an example.