Last updated Sep 6, 2021

Rate this page:

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.

Association with a components

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
3
4
5
6
7
8
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.
ownerId: null
fields:
  tier: 1
links: []
relationships: {}

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
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.
ownerId: 'ari:cloud:teams::team/00000000-0000-0000-0000-000000000000'
fields:
  tier: 1
links:
  - name: My Jira project
    type: PROJECT
    url: 'https://www.example.com/projects/myproject'
  - name: How to use my-service
    type: DOCUMENT
    url: 'https://www.example.com/user-guide/how+to+use+my+service'
  - name: null
    type: OTHER_LINK
    url: 'https://www.example.com/resources/'
  - name: Service dashbaord
    type: DASHBOARD
    url: 'https://www.example.com/dashboards/service-dashboard'
  - name: Service repository
    type: REPOSITORY
    url: 'https://www.example.com/repos/my-service-repo'
relationships:
  DEPENDS_ON:
    - 'ari:cloud:compass:00000000-0000-0000-0000-000000000000:component/00000000-0000-0000-0000-000000000000/00000000-0000-0000-0000-00000000000'
    - 'ari:cloud:compass:00000000-0000-0000-0000-000000000000:component/00000000-0000-0000-0000-000000000000/00000000-0000-0000-0000-00000000000'

Contents of a compass.yml file

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

  • 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
    name: Your component name goes here
  • id (required)

    An unique, unchangeable identifier of the component in Compass. The id must match an existing component in your Compass catalog. The Bitbucket integration uses the id to determine which component your compass.yml file refers to. Learn how to find a component's ID

    The id has the following format:

    1
    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.

  • description (optional)

    The description of the component, in plain text.

    1
    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
    3
    4
    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
    description: null
  • ownerId (optional)

    An unique identifier of the team that owns the component. If specified, the ownerId must match a team in your Atlassian organization. Find a team's ID.

    The ownerId has the following format:

    1
    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
    ownerId: null
  • fields: tier (required for components of type SERVICE, invalid for all other types)

    The Service tier of the component. The accepted values are:

    • 1 (highest importance)
    • 2
    • 3
    • 4 (lowest importance)

    For components of type SERVICE, nest tier under fields, as follows:

    1
    2
    fields:
      tier: 3

    For components of types other than SERVICE, leave fields empty.

    1
    fields: {}

    The tier field is only valid for components of type SERVICE. For other component types, if you add a tier field, the update fails.

  • links (optional)

    A list of the links to a component’s resources such as a Jira project, dashboards, documentation, 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
      • DOCUMENT
      • DASHBOARD
      • ON_CALL (available for components of type SERVICE, invalid for all other types)
      • 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
    3
    4
    5
    6
    7
    links:
      - name: 'My documentation'
        type: DOCUMENT
        url: 'https://www.example.com/document/'
      - 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
    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 in your Compass catalog.

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

    1
    2
    3
    4
    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 component does not depend on any other components, leave relationships empty.

    1
    relationships: {}

File validation

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

Rate this page: