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.
The configuration file should be named compass.yml or compass.yaml.
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.
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 2configVersion: 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 2configVersion: 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. ownerId: 'ari:cloud:teams::team/00000000-0000-0000-0000-000000000000' typeId: SERVICE fields: tier: 1 lifecycle: Active 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 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' - 'ari:cloud:compass:00000000-0000-0000-0000-000000000000:component/00000000-0000-0000-0000-000000000000/00000000-0000-0000-0000-00000000000'
Here’s a description of each attribute in the compass.yml file:
configVersion (optional)
The only supported version right now is 1.
1 2configVersion: 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 2name: 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 2id: '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 2description: Your component description goes here.
To specify a multi-line description, begin the value with |- and indent each line of the description:
1 2description: |- 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 2description: null
typeId (optional)
Set the component's type by using the typeId field. Acceptable values are:
APPLICATIONSERVICECAPABILITYCLOUD_RESOURCEDATA_PIPELINELIBRARYMACHINE_LEARNING_MODELOTHERUI_ELEMENTWEBSITEownerId (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 2ownerId: '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 2ownerId: null
fields: tier
The Service tier of the component. The accepted values are:
1 (highest importance)234 (lowest importance)Nest tier under fields, as follows:
1 2fields: tier: 3
Or leave fields empty.
1 2fields: {}
fields: lifecycle (optional)
The current lifecycle status of the component. The accepted values are:
Pre-releaseActiveDeprecatedNest lifecycle under fields, as follows:
1 2fields: lifecycle: Active
Or leave fields empty.
1 2fields: {}
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_CHANNELDOCUMENTDASHBOARDON_CALLPROJECTREPOSITORYOTHER_LINKurl (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 2links: - 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 2links: []
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. Learn how to find a component's ID
Here’s a sample that shows a component’s relationship with two other components:
1 2relationships: 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 2relationships: {}
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:
textbooleannumberusersingle_selectmulti_selectvalue (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 ID of a single select option.multi_select: A 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 2customFields: - 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'
If a component does not have any custom fields, leave the list empty.
1 2customFields: []
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 2labels: - "foo:bar" - "baz"
If a component does not have any labels, leave the list empty.
1 2labels: []
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.
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.
Rate this page: