Config as Code (opslevel.yml)
You can define OpsLevel components and ownership info by placing an opslevel.yml file in your git repos. OpsLevel will automatically synchronize these files whenever they change.
In addition to defining components through OpsLevel’s UI and GraphQL API, you can also define components by placing a YAML file named opslevel.yml
in a component’s repo. Leveraging our Git Repository Integrations, OpsLevel will automatically synchronize the contents of the opslevel.yml
file whenever it changes. This config-as-code mechanism allows developers to retain their existing Git-based development workflows to keep this data up-to-date.
In addition to components, opslevel.yml
can also track ownership and metadata about repositories. The contents of opslevel.yml
differ depending on if it’s tracking a component or a repository. The schema below highlights these differences.
YAML Specification
OpsLevel uses YAML 1.1, to ensure that values are treated as strings it is highly recommended to use quotes (
"
) around values. This ensures that tag values such asfalse
are not converted to Booleans
Supported file extension: .yml
Only the .yml
file extension is supported. .yaml
will not be detected.
Ensure the file is namedopslevel.yml
to be auto-detected.
Aliases
opslevel.yml
uses human readable identifiers to specify the owner, or tier of a component or repository, as well as the lifecycle stage of a component. For example, an opslevel.yml
that specifies the team that owns a component looks like:
component:
name: Order Processor
type: service
owner: orders_team
The identifier orders_team
is an alias. Aliases are automatically generated by OpsLevel for teams, tiers, and lifecycles.
Finding the alias for a component
Navigate to the Customization page. The aliases will be listed as a column in the table.

Finding the alias for a team
Navigate to a Team page. There you can find the team alias.

Finding the alias for a tier
Navigate to the Account page. From there you will see a list of all your Component Tiers and their aliases. Currently, only users with the Admin role have access to the Account page. Non-Admin users can access this information with the OpsLevel CLI using the opslevel list tier
command.

Finding the alias for a lifecycle
Similar to Component Tiers, navigate to the Account page. From there you will see a list of all your Component Lifecycles and their aliases. Currently, only users with the Admin role have access to the Account page. Non-Admin users can access this information with the OpsLevel CLI using the opslevel list lifecycle
command.

Alias Stability
Aliases are stable identifiers. If you rename an entity that has an alias (e.g., a team), OpsLevel will generate a new alias. However, the old alias will still be valid so any existing references to it from other opslevel.yml
files will continue to work.
Converting an existing component to use opslevel.yml
If you have a component already defined in OpsLevel and want it to be managed with opslevel.yml
, first ensure the component is already connected to a repo. When a component is connected to a repo, OpsLevel will know how to merge a newly detected opslevel.yml
with the component. After the repo is connected to the component, you can download the component’s opslevel.yml file and commit it to the repo.
Step 1: Visit a component’s Summary tab and select the repository your component lives in by clicking Edit and + Add Repository.


Step 2: From the component page click the Download opslevel.yml
button.

Step 3: Copy the contents or Download the opslevel.yml
and commit to the repo you selected in Step 1.

Converting an existing repository to use opslevel.yml
You can use opslevel.yml
to manage properties directly on a repository, such as: owner
, tier
, and tags
.
Step 1: Select a repository that was imported using one of our Git Repository Integrations.
Step 2: From the repository page click the Download opslevel.yml
button.

Step 3: Copy the contents or Download the opslevel.yml
and commit to this repo.

Schema
The following tables provide an in depth list of all the properties supported by opslevel.yml
.
Note: opslevel.yml
currently only supports one top-level field of either component
, repository
, or service
(deprecated) . In the event that more than one is specified, the component
section will take precedence.
Component
Attribute | Required | Description |
---|---|---|
name | true | The name of the component. |
type | true | The type of the component. Please refer to the Aliases section for more details. |
description | false | The component description. |
owner | false | The owner of the component. Must provide a valid team alias. Please refer to the Aliases section for more details. |
lifecycle | false | The lifecycle the component is currently in. Must provide a valid lifecycle alias. Please refer to the Aliases section for more details. |
tier | false | The tier of the component. Must provide a valid tier alias. Please refer to the Aliases section for more details. |
system | false | The system the component belongs to. |
product | false | The product the component belongs to. |
language | false | The core language the component is written in. |
framework | false | The core framework used for the component. |
aliases | false | A list of all user defined aliases for this component. |
tags | false | A list of all key value tags defined for this component. Please refer to Tags section below for more details. |
tools | false | A list of all tools used by this component. Please refer to Tools section below for more details. |
repositories | false | A list of all repositories associated with this component. Please refer to Repositories section below for more details. |
dependencies | false | A list of all dependencies for this component. Please refer to Dependencies section below for more details. |
alert sources | false | A list of all alert sources for this component. Please refer to Alert Sources section below for more details. |
properties | false | An object consisting of Property Definitions aliases as keys and values to be set on the component. Please refer to Custom Component Properties section for more details. |
Service (Deprecated)
Using the service
top level attribute is still supported, but deprecated. It will create a component with a type service
.
Attribute | Required | Description |
---|---|---|
name | true | The name of the service. |
description | false | The service description. |
owner | false | The owner of the service. Must provide a valid team alias. Please refer to the Aliases section for more details. |
lifecycle | false | The lifecycle the service is currently in. Must provide a valid lifecycle alias. Please refer to the Aliases section for more details. |
tier | false | The tier of the service. Must provide a valid tier alias. Please refer to the Aliases section for more details. |
system | false | The system the service belongs to. |
product | false | The product the service belongs to. |
language | false | The core language the service is written in. |
framework | false | The core framework used for the service. |
aliases | false | A list of all user defined aliases for this service. |
tags | false | A list of all key value tags defined for this service. Please refer to Tags section below for more details. |
tools | false | A list of all tools used by this service. Please refer to Tools section below for more details. |
repositories | false | A list of all repositories associated with this service. Please refer to Repositories section below for more details. |
dependencies | false | A list of all dependencies for this service. Please refer to Dependencies section below for more details. |
alert sources | false | A list of all alert sources for this service. Please refer to Alert Sources section below for more details. |
properties | false | An object consisting of Property Definitions aliases as keys and values to be set on the service. Please refer to Custom Service Properties section for more details. |
Repository
Attribute | Required | Description |
---|---|---|
owner | false | The owner of the repository. Must provide a valid team alias. Please refer to the Aliases section for more details. |
tier | false | The tier of the repository. Must provide a valid tier alias. Please refer to the Aliases section for more details. |
tags | false | A list of all key value tags defined for this repository. Please refer to Tags section below for more details. |
Attributes
Tags
Attribute | Required | Description |
---|---|---|
key | true | The tag key. |
value | true | The tag value. |
Tools
Attribute | Required | Description |
---|---|---|
category | true | The category the tool belongs to. Valid categories are admin , api_documentation , code , continuous_integration , deployment , errors , feature_flag , health_checks , incidents , issue_tracking , logs , metrics , orchestrator , resiliency , runbooks , security_scans , status_page , wiki , and other . |
url | true | The url pointing to the tool. |
name | false | The display name used for the tool |
environment | false | The environment this tool is used in. ex. Production, Staging. |
Repositories
Attribute | Required | Description |
---|---|---|
name | true | The repository name. The format needs to include the Organization/Group/Workspace that it belongs to, e.g. my-github-org/my-repo , my-gitlab-group/my-repo , my-bitbucket-workspace/my-repo . |
provider | true | The git provider where your repository is stored. |
display_name | false | The repository name displayed on the component page. |
path | false | The path repository containing the opslevel.yml and where repository checks are applied. This is useful in monorepo situations where multiple components are contained in one repository. |
Dependencies
Attribute | Required | Description |
---|---|---|
alias | true | The alias of the component. |
notes | false | Additional information about the dependency. |
Alert Sources
Attribute | Required | Description |
---|---|---|
type | true | The type of integration where the alert source was created from. Options include datadog , opsgenie and pagerduty . |
external_id | true | The unique identifier from the integrated tool where the alert source came from. For example, a Pagerduty external_id would be the Pagerduty service's service.id |
JSON Schema
You can automatically validate your opslevel.yml
file as part of your CI using the following JSON schema: opslevel.schema.yml
You can run the following command which uses ajv-cli.
ajv test -s opslevel.schema.yml -d opslevel.yml --valid
Locking
When a component or repository is managed by opslevel.yml
, certain fields are locked. This locking applies across all methods of modifying the component, whether in the UI or various methods that go through the GraphQL API. This ensures that there is never a conflict between what’s defined in opslevel.yml
and what’s defined in OpsLevel.
For components the name
, description
, owner
, tier
, system
, lifecycle stage
, language
, and framework
fields are all locked for editing.
For repositories the owner
and tier
fields are locked for editing.
Component and repository properties that are lists, such as tools, tags, aliases, dependencies, and repositories, can have new entries added in the UI, though existing entries defined in opslevel.yml
will be locked.
As shown in the image below, to tell whether a component or repository is managed by opslevel.yml
, you can look for a lock icon on the respective information page.
Locked Component

Locked Repository

Locked Component Dependency

Component locked from being added to a System

Component locked from being added to a System
Resyncing the opslevel.yml
If a config file error occurs due to a change elsewhere (ex. a component dependency has been renamed or alias has been deleted), the Resync button can be used to update the component with the latest fetched opslevel.yml after making the necessary change (ex. add the referenced alias to the correct component). This can be more convenient in some cases instead of unnecessary commits to trigger OpsLevel to re-evaluate the opslevel.yml.

Select "Resync" to update the component based on the latest fetched opslevel.yml
Example component opslevel.yml
---
version: 1
component:
name: Shopping Cart Service
type: service
lifecycle: generally_available
tier: tier_1
system: web
product: Retail Website
owner: order_management_team
language: Ruby
framework: Rails
description: Allows users to add/remove products in their virtual shopping carts
prior to placing an order.
aliases:
- cart
tags:
- key: db
value: mysql
- key: kafka-topic
value: cart-additions
repositories:
- name: DunderMifflin/shopping_cart
path: "/"
provider: github
display_name: Cart Service Code
- name: DunderMifflin/TerraformRepo
path: "/production/shopping_cart"
provider: bitbucket
display_name: Terraform Config
tools:
- name: Confluence
category: runbooks
url: http://company.atlassian.com/confluence/runbooks
- name: PagerDuty
category: incidents
url: https://your_account.pagerduty.com/services/PH99999
environment: Production
- name: Datadog
category: metrics
url: https://app.datadog.com/your_dashboard?env=prod
environment: Production
- name: Datadog
category: metrics
url: https://app.datadog.com/your_dashboard?env=staging
environment: Staging
dependencies:
- alias: recommendation_service
notes: Provides products recommendations to enhance the users shopping experience
- alias: suggestions_service
alert_sources:
- type: pagerduty
external_id: ABCD123
- type: opsgenie
external_id: 1234567-abcd-1234-abcdefgh1234
- type: datadog
external_id: 1234567
Example repository opslevel.yml
---
version: 1
repository:
tier: tier_1
owner: order_management_team
tags:
- key: version
value: v1.0.0
Templating
If your organization uses template repositories for creating new components or repositories, you will benefit from using opslevel.defaults.yml
as a templating mechanism.
opslevel.defaults.yml
allows you to specify default values for your components or repositories that will be applied once you add an opslevel.yml
file. Values set in the opslevel.defaults.yml
file will be overwritten by values from the opslevel.yml
file.
It is recommended you add an opslevel.defaults.yml
file to your template repository with some basic defaults set; these are often in the form of a default language/framework, default tags, default tools, and possibly more.
Format
The format of opslevel.defaults.yml
is identical to that of opslevel.yml
. The only difference is that the opslevel.defaults.yml
file limits which values you can set.
Values you can set from opslevel.defaults.yml
:
Component | Repository |
---|---|
type | tier |
tier | owner |
owner | tags |
system | |
tags | |
description | |
lifecycle | |
product | |
language | |
framework | |
repositories | |
tools |
Like with opslevel.yml
, you can validate your opslevel.defaults.yml
file using the following JSON schema: opslevel.defaults.schema.yml.
FAQs
Where do I put the opslevel.yml file?
Just add your opslevel.yml
file(s) to your repo. If you specify a component
definition in this file and this repo isn’t already mapped to a component in OpsLevel, a new component will be created.
Note: OpsLevel will only look for files that use the .yml
extension.
Is opslevel.yaml
supported?
opslevel.yaml
supported?No, at this time we do not support looking for opslevel.yaml
. Please ensure the .yml
extension is used.
For a mono-repo with many components, is it possible to define multiple opslevel.yml files in one repo or multiple components in a single file?
It is not possible to define multiple components in a single opslevel.yml file, however you can define multiple opslevel.yml files in different subdirectories of a repo. Add an opslevel.yml file into each subdirectory, and OpsLevel will automatically detect the yml file and create a new component in the catalog, or lock the existing component with the linked repo.
I have two components that are both locked by the same repo and opslevel.yml, how do I delete the duplicate component if it’s a duplicate?
If you attach a repo to a component that is already locking a different component, we will apply the opslevel.yml to the new component and subsequently lock it.
In order to delete this component, you must first delete the repository connection on the duplicate component, which will unlock the component and allow you to delete it.
How can I get a list of all opslevel.yml errors?
Our GraphQL API can return these errors on the configErrors
field under Component
and Repository
objects.
What happens if I delete the opslevel.yml file, does the component get deleted?
When the opslevel.yml
file is deleted, the component becomes unlocked in your OpsLevel account. Any remaining data that was defined in the opslevel.yml
will be preserved on the component.
You can then delete the component via the UI/API if that was the desired next step.
If you have more questions?
Just send us an email at [email protected].
Updated 29 days ago