Last updated Apr 21, 2025

Structure and contents of a compass.yml file

Compass uses a YAML configuration file, compass.yml to manage a component’s details via configuration as code (config as code). Let’s take a look at the file’s structure and contents.

Filename

The configuration file should be named compass.yml or compass.yaml.

Association with a component

Each component can have only one compass.yml file associated with it. The file contains a component’s unique identifier, which associates each file with its corresponding component.

To declare multiple components within the same repository, use multiple compass.yml files in separate subfolders.

Structure of a compass.yml file

The compass.yml file contains key-value pairs that describe a component’s details. The key represents the component’s attribute, whereas the value represents the actual value of that attribute in Compass.

Here’s an example of a compass.yml file that declares only a few details of a Service-type component:

1
2
configVersion: 1
name: my-service
id: 'ari:cloud:compass:a0000000-b000-c000-d000-e00000000000:component/00000000-0000-0000-0000-000000000000/00000000-0000-0000-0000-000000000000'
description: This is a sample component in Compass.
typeId: SERVICE
ownerId: null
fields: {}
labels: []
links: []
customFields: []
relationships: {}

Here’s another sample structure of the file that declares more details of the same component:

1
2
configVersion: 1
name: my-service
slug: my-service
id: 'ari:cloud:compass:a0000000-b000-c000-d000-e00000000000:component/00000000-0000-0000-0000-000000000000/00000000-0000-0000-0000-000000000000'
description: This is a sample component in Compass.
ownerId: 'ari:cloud:teams::team/00000000-0000-0000-0000-000000000000'
typeId: SERVICE
fields:
  tier: 1
  lifecycle: Active
  isMonorepoProject: false
links:
  - name: My Jira project
    type: PROJECT
    url: 'https://www.example.com/projects/myproject'
  - name: null
    type: OTHER_LINK
    url: 'https://www.example.com/resources/'
  - name: Service dashboard
    type: DASHBOARD
    url: 'https://www.example.com/dashboards/service-dashboard'
  - name: Service repository
    type: REPOSITORY
    url: 'https://www.example.com/repos/my-service-repo'
labels:
  - foo:bar
  - baz
customFields:
  - name: platform
    type: text
    value: web
  - name: reviewed
    type: boolean
    value: true
relationships:
  DEPENDS_ON:
    - 'ari:cloud:compass:00000000-0000-0000-0000-000000000000:component/00000000-0000-0000-0000-000000000000/00000000-0000-0000-0000-00000000000'
    - my-other-service-slug

Contents of a compass.yml file

Here’s a description of each attribute in the compass.yml file:

configVersion (optional)

The only supported version right now is 1.
```
1
2
configVersion: 1
```
name (required)

The display name of the component in Compass, in plain text. The name is not required to be unique, but we recommend using a unique name to prevent confusion among components.
```
1
2
name: Your component name goes here
```
id (optional)

A unique, unchangeable identifier of the component in Compass and the best way to guarantee you are referencing what component is being managed by the YAML file. The id must match an existing component in your Compass catalog. Learn how to find a component's ID. Omit the id only when creating a new component from YAML but be sure to add it after the component is created in Compass. It is highly recommended to always use an id to guarantee the correct component is referenced even if the YAML file is moved.

The id has the following format:
```
1
2
id: 'ari:cloud:compass:00000000-0000-0000-0000-000000000000:component/00000000-0000-0000-0000-000000000000/00000000-0000-0000-0000-000000000000'
```
Enclose the entire value of the id in single quotes.
slug (optional)

A unique, human-readable string that identifies the component in Compass. It can be used instead of the component ID or ARI in some APIs. This slug must be unique within your Compass organization, contain only letters, numbers, and hyphens, and be between 1 and 64 characters.
```
1
2
slug: your-component-slug
```

description (optional)

The description of the component, in plain text.

1
2
description: Your component description goes here.

To specify a multi-line description, begin the value with |- and indent each line of the description:

1
2
description: |-
  This is a multi-line description.
  Here's the second line.
  And the third.

If the component does not have a description, set the value to null:

1
2
description: null

typeId (optional)

Set the component's type by using the typeId field. Acceptable values are:
- APPLICATION
- SERVICE
- CAPABILITY
- CLOUD_RESOURCE
- DATA_PIPELINE
- LIBRARY
- MACHINE_LEARNING_MODEL
- OTHER
- UI_ELEMENT
- WEBSITE

If you are using a custom component type, you can reference it using its display name (i.e. GitHub Action) or its ARI (i.e. ari:cloud:compass:00000000-0000-0000-0000-000000000000:component-type/00000000-0000-0000-0000-000000000000).

Learn more about component types.

ownerId (optional)

A unique identifier of the team that owns the component. If specified, the ownerId must match a team in your Atlassian organization. Learn how to find a team's owner ID

The ownerId has the following format:
```
1
2
ownerId: 'ari:cloud:teams::team/00000000-0000-0000-0000-000000000000'
```
Enclose the entire value of the ownerId in single quotes.

If the component does not have an owner team, set the value to null:
```
1
2
ownerId: null
```
fields: tier

The Service tier of the component. The accepted values are:
- 1 (highest importance)
- 2
- 3
- 4 (lowest importance)
Nest tier under fields, as follows:
```
1
2
fields:
  tier: 3
```
Or leave fields empty.
```
1
2
fields: {}
```
fields: lifecycle (optional)

The current lifecycle status of the component. The accepted values are:
- Pre-release
- Active
- Deprecated
Nest lifecycle under fields, as follows:
```
1
2
fields:
  lifecycle: Active
```
Or leave fields empty.
```
1
2
fields: {}
```
fields: isMonorepoProject

A boolean field that indicates whether this component is part of a monorepo project. Please note that setting this field to true will stop the automatic processing of build, deployment and PR metrics for this component. The accepted values are:
- true
- false
Nest isMonorepoProject under fields, as follows:
```
1
2
fields:
  isMonorepoProject: false
```
links (optional)

A list of the links to a component’s resources such as a Jira project, dashboards, and more. Learn more about the available link types

Specify each link by using the following parameters:
- type (required): The type of link. The acceptable values are:
  - CHAT_CHANNEL
  - DASHBOARD
  - ON_CALL
  - PROJECT
  - REPOSITORY
  - OTHER_LINK
- url (required): The actual URL of the link, beginning with http:// or https://.
- name (optional): The display name of the link, in plain text, that Compass will show instead of the url. If you omit this or set it to null, Compass attempts to resolve the url and display its title.
You can add multiple links in the compass.yml file. See the following sample format:
```
1
2
links:
  - name: 'My dashboard'
    type: DASHBOARD
    url: 'https://www.example.com/dashboard/'
  - name: 'My respository'
    type: REPOSITORY
    url: 'https://www.example.com/repo/'
```
If a component does not have any links, leave the links list empty.
```
1
2
links: []
```

relationships : DEPENDS_ON (optional)

A list of the other components that a component depends on. Learn more about the available dependency types

List the components under DEPENDS_ON. Each item in the list must match a component's id or slug in your Compass catalog. Learn how to find a component's ID

Here’s a sample that shows a component’s relationship with two other components:

1
2
relationships:
  DEPENDS_ON:
    - 'ari:cloud:compass:00000000-0000-0000-0000-000000000000:component/00000000-0000-0000-0000-000000000000/00000000-0000-0000-0000-000000000000'
    - 'ari:cloud:compass:00000000-0000-0000-0000-000000000000:component/11111111-0000-0000-0000-000000000000/00000000-0000-0000-0000-000000000000'

If the components being referenced both have component slugs, you can also use their slugs in this field:

1
2
relationships:
  DEPENDS_ON:
    - your-component-slug
    - your-other-component-slug

If the component does not depend on any other components, leave relationships empty.

1
2
relationships: {}

customFields (optional) A list of the custom fields to set values for. The custom fields must already exist in your Compass site and you need the case-sensitive name and type of each field. Learn more about custom fields Specify each custom field value to set by using the following parameters:

type (required): The type of custom field. The acceptable values are:
- text
- boolean
- number
- user
- single_select
- multi_select
value (required): The value you'd like to set for the custom field. Acceptable values for each type are:
- text: A string.
- boolean: true or false.
- number: A number.
- user: An ARI of a Compass user.
- single_select: The text display value or ID of a single select option.
- multi_select: The text display values or list of IDs of multi select options.
name (required): The name of the custom field (case sensitive).

You can add multiple custom fields in the compass.yml file. See the following sample format:

1
2
customFields:
  - name: 'Date of last security review'
    type: text
    url: '2023-03-09'
  - name: 'Requires audit?'
    type: boolean
    value: false
  - name: 'Number of users'
    type: number
    value: 100
  - name: 'Owner'
    type: user
    value: 'ari:cloud:compass:00000000-0000-0000-0000-000000000000:user/00000000-0000-0000-0000-000000000000'
  - name: 'Status'
    type: single_select
    value: '00000000-0000-0000-0000-000000000000'
  - name: 'Tags'
    type: multi_select
    value:
      - '00000000-0000-0000-0000-000000000000'
      - '11111111-0000-0000-0000-000000000000'

For single_select and multi_select fields, you can also refer to their displayValue instead of their value. This display value must exactly match the text value of that option.

1
2
  - name: 'Status'
    type: single_select
    displayValue: 'APPROVED'
  - name: 'Tags'
    type: multi_select
    displayValue:
      - 'tag-value-1'
      - 'tag-value-2'

If a component does not have any custom fields, leave the list empty.

1
2
customFields: []

labels (optional) A list of labels to apply to the component. Each label is a string.

You can add multiple labels in the compass.yml file. See the following sample format:
```
1
2
labels:
  - "foo:bar"
  - "baz"
```
If a component does not have any labels, leave the list empty.
```
1
2
labels: []
```

Removing a custom field from a component

If you want to delete the value of a custom field from a component, you can do so by setting its value to empty string in the compass.yml file.

For example, to remove the value of a custom field named Date of last security review from this component, set its value to empty as shown below:

1
2
customFields:
  - name: 'Date of last security review'
    type: text
    value: ''

File validation

After you commit the compass.yml file to your repository, Compass validates the file before processing any updates.

If the compass.yml file is invalid, Compass rejects the update and does not make any changes to the component. You’ll know there is a problem if the component details aren’t updated in Compass within a few seconds.
If your updates to compass.yml file aren’t being processed, verify the following:
The YAML syntax is valid. You can check the syntax using an online tool such as YAML Validator.
You've provided all the required fields, and have spelled all the field names correctly.
You specify a valid value for fields accepting a limited set of values, such as tier.
The id and any relationships match existing components in your Compass catalog.
- If you created your component from YAML and the component does not have an id added to it yet, try adding the component id to the yaml file to ensure that the component is connected.
The ownerId matches an existing team in your Atlassian organization.