Every service that has been imported into Cortex is represented by a unique YAML file, which is automatically generated for you during the import flow. You can access a service’s YAML file at any time from a service's home page.

You have the ability to continue editing a service indefinitely, so you’re never locked into your initial import. There are two ways to edit your service: through the GitOps flow or through the Cortex UI. 

Cortex UI

You can edit a service directly through Cortex’s UI, which we recommend for those just getting started with Cortex — it’s easy to enter information, and you don’t have to think about tinkering with the YAML file.

Once you select a service from the catalog, you'll see Configure Service on its home page. 

From this page, you can enter and modify all the high-level metadata about your service: name, description, tags, owners, dependencies, runbook links, oncall information, and dependencies. Any edits made here will be automatically reflected in the YAML file, so the editing process is seamless.

At any time, you can select Switch to cortex.yaml to directly edit a service through it's YAML file.

Directly editing the YAML is recommended after you've entered in all the essential metadata and are ready to move into API documentation and other advanced features.

This approach gives you the ability to change just about anything. You can view more about what's available through the Service Descriptor Docs, as well as the Reference section, which provides more detail about working with specific integrations to incorporate data into the YAML or catalog.

Every time you save changes, Cortex will automatically refresh the service for you. Plus, if you happen to make any missteps along the way, Cortex will supply error codes and suggestions for fixes.

Cortex will also automatically re-evaluate scorecards every time a service is updated. If the edits you make impact your scorecard rules, you’ll see changes to your scores reflected within a few minutes. If you have Slack integrated, you’ll receive a notification from the Cortex Slack bot with detailed information about how the score changed.

GitOps flow

To edit a service through GitOps, add the service's YAML file into your Git repository, and Cortex will automatically pull changes any time you push code to the master branch.

This approach is recommended for organizations who want their service information and documentation to live alongside their code. In this case, the YAML file also serves as version control, so you can easily see what changes have been made. 

With a GitOps flow, you won’t need to make any edits in Cortex — that’ll be taken care of automatically. Because this is a more robust option, organizations typically adopt a GitOps model once they’re ready to roll out across their entire organization. You can find more information about what this flow looks like in our GitOps documentation.

Disabling the UI editor

In order to use the GitOps workflow, you have to disable the UI editor in Cortex, or the services won't sync properly. Edits made in the UI could override a Git version, or vice versa, making it hard to know which version is true.

To disable the UI editor, navigate to My Preferences, and then App Preferences on the left-hand side. You’ll see an option to toggle the UI Editor for services and resources.

Skip editing altogether

In many cases, you don’t need to edit a service to get information into Cortex — the platform can automatically pull it for you. Most integrations have a service registration section in our docs, like with Datadog, to walk you through the process of connecting a service in the catalog to information about it. This is functionally the same as editing a service, but saves you time and effort.

Using the discovery feature bypasses all edits to the YAML by pulling that info directly from the source. For example, if you’ve tagged your Datadog monitors and alerts in Cortex, the two will be mapped to each other, and Cortex will automatically display relevant information. We recommend using discovery whenever possible to enforce standardization and consistency in how integrations are used.

If you’d rather hardcode or override the discovery feature, you can use the service descriptors available in the documentation and edit the YAML accordingly.