In addition to defining services through OpsLevel’s UI and GraphQL API, you can also define services by placing a YAML file named
opslevel.yml in a service’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 services,
opslevel.yml can also track ownership and metadata about repositories. The contents of
opslevel.yml differ depending on if it’s tracking a service or a repository. The schema below highlights these differences.
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 as
falseare not converted to Booleans
opslevel.yml uses human readable identifiers to specify the owner, or tier of a service or repository, as well as the lifecycle stage of a service. For example, an
opslevel.yml that specifies the team that owns a service looks like:
service: name: Order Processor owner: orders_team
orders_team is an alias. Aliases are automatically generated by OpsLevel for teams, tiers, and lifecycles.
Navigate to a Team page. There you can find the team alias.
Navigate to the Account page. From there you will see a list of all your Service 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.
Similar to Service Tiers, navigate to the Account page. From there you will see a list of all your Service 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.
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.
If you have a service already defined in OpsLevel and want it to be managed with
opslevel.yml, first ensure the service is already connected to a repo. When a service is connected to a repo, OpsLevel will know how to merge a newly detected
opslevel.yml with the service. After the repo is connected to the service, you can download the service’s YAML file and commit it to the repo.
Step 1: Visit a service’s Operation tab and select the repository your service lives in from the Repository Center by clicking Edit and + Add Repository.
Step 2: From the service page click the Download YAML button.
Step 3: Copy or Download the YAML and commit to the repo you selected in Step 1.
You can use
opslevel.yml to manage properties directly on a repository, such as:
Step 1: Select a repository that was imported using one of our Git Repository Integrations.
Step 2: From the repository page click the Download YAML button.
Step 3: Copy or Download the YAML and commit to this repo.
The following tables provide an in depth list of all the properties supported by
opslevel.yml currently only supports one top-level field of either
service. In the event that both are specified, the
service section will take precedence.
|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.|
|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.|
|key||true||The tag key.|
|value||true||The tag value.|
|category||true||The category the tool belongs to. Valid categories are |
|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.|
|name||true||The repository name. The format needs to include the Organization/Group/Workspace that it belongs to, e.g. |
|provider||true||The git provider where your repository is stored.|
|display_name||false||The repository name displayed on the service page.|
|path||false||The path repository containing the opslevel.yml and where repository checks are applied. This is useful in monorepo situations where multiple services are contained in one repository.|
|notes||false||Additional information about the dependency.|
|type||true||The type of integration where the alert source was created from. Options include |
|external_id||true||The unique identifier from the integrated tool where the alert source came from. For example, a Pagerduty |
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
When a service or repository is managed by
opslevel.yml, certain fields are locked for edit in the UI. This ensures that there is never a conflict between what’s defined in
opslevel.yml and what’s defined in the UI.
For services the
framework fields are all locked for editing.
For repositories the
tier fields are locked for editing.
Service 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 service or repository is managed by
opslevel.yml, you can look for a lock icon on the respective information page.
version: 1 service: name: Shopping Cart 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
version: 1 repository: tier: tier_1 owner: order_management_team tags: - key: version value: v1.0.0
If your organization uses template repositories for creating new services 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 services 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
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.
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
Just add your
opslevel.yml file(s) to your repo. If you specify a
service definition in this file and this repo isn’t already mapped to a service in OpsLevel, a new service will be created.
Note: OpsLevel will only look for files that use the
I have two services that are both locked by the same repo and opslevel.yml, how do I delete the duplicate service if it’s a duplicate?
If you attach a repo to a service that is already locking a different service, we will apply the opslevel.yml to the new service and subsequently lock it.
In order to delete this service, you must first delete the repository connection on the duplicate service, which will unlock the service and allow you to delete it.
Our GraphQL API can return these errors on the
configErrors field under
Just send us an email at [email protected].
Updated about 2 months ago