Rate this page:
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
.
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
(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 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:
APPLICATION
SERVICE
CAPABILITY
CLOUD_RESOURCE
DATA_PIPELINE
LIBRARY
MACHINE_LEARNING_MODEL
OTHER
UI_ELEMENT
WEBSITE
ownerId
(optional)
An 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
(required for components of type SERVICE, CAPABILITY, CLOUD_RESOURCE, DATA_PIPELINE, MACHINE_LEARNING_MODEL, UI_ELEMENT, WEBSITE
, invalid for components of type APPLICATION, LIBRARY, OTHER
)
The Service tier of the component. The accepted values are:
1
(highest importance)2
3
4
(lowest importance)For components of type SERVICE, CAPABILITY, CLOUD_RESOURCE, DATA_PIPELINE, MACHINE_LEARNING_MODEL, UI_ELEMENT, WEBSITE
, nest tier
under fields
, as follows:
1 2fields: tier: 3
For components of type APPLICATION, LIBRARY, OTHER
, leave fields
empty.
1 2fields: {}
The tier
field is only valid for components of type SERVICE, CAPABILITY, CLOUD_RESOURCE, DATA_PIPELINE, MACHINE_LEARNING_MODEL, UI_ELEMENT, WEBSITE
. For other component types, if you add a tier
field, the update fails.
fields
: lifecycle
(optional)
The current lifecycle status of the component. The accepted values are:
Pre-release
Active
Deprecated
1 2fields: lifecycle: Active
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
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 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:
text
boolean
number
user
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.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
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.
The ownerId
matches an existing team in your Atlassian organization.
Rate this page: