Last updated May 14, 2025

Manage components with config as code

Configuration as code (config as code) allows you to manage Compass component data via a YAML file that is stored in a git repository. Config as code requires the Bitbucket, GitHub, or GitLab app to be installed and configured on your Compass site. With config as code, you declare component details in a compass.yaml file that sits alongside the source code or configuration for the component itself. The component then becomes a managed component in Compass. You can manage existing components this way or create new components in Compass by simply committing a compass.yaml file. Learn more about how config as code works.

Here, we’ll take you through the process of creating a new component from YAML, setting up config as code for a component existing in Compass already, and also show you how you can manage multiple components from the same repository (e.g. monorepos).

Before you begin

A Compass admin must install and configure one of the supported apps: Bitbucket Cloud, GitHub Cloud, or GitLab.com.
Have some basic experience with using Git and familiarize yourself with adding and editing files in Bitbucket Cloud, GitHub, or GitLab.com. Learn how to add, edit, and commit to source files in a Bitbucket repository, learn how to manage files in GitHub, or learn how to manage files in GitLab
Have a basic understanding of YAML file structures.
Familiarize yourself with the structure and contents of the compass.yml file.

Create a component with config as code

You can create a component in Compass by adding a compass.yaml file to any git repository in a connected Bitbucket Workspace, GitHub Organization, or GitLab Project. When Compass sees the file committed to your default branch, it will use the data provided in the YAML file to bootstrap a new Compass component and automatically link the repository to the component for you. It is highly recommended you add the component's id to your compass.yaml file after the component gets created in Compass (learn how to find a component's ID).

Create a compass.yaml file. Ensure you have given your component a name. Do not add an id field to the file, since no compass component exists yet.
Commit the compass.yaml file to the default branch of your repository.
Verify the component was created in the Compass UI by searching for it by the name you used. If you forgot to add a name, search for "Unnamed component".
Update the YAML file to modify component data going forward.

If a compass.yml file is invalid, Compass rejects the update for that component. You’ll know there is a problem if the component details aren’t updated in Compass within a few seconds. Check the contents of the file, fix any errors, and merge your changes with the repository’s default branch. Learn more about file validation

It is important you add a component ID to your compass.yaml after you create the component to ensure Compass is able to properly track management of the component should the yaml file or repository be moved or renamed.

From here onwards, every time you update the compass.yaml file and commit those changes to your repository’s default branch, the changes automatically sync back to Compass and are reflected in your component’s details. Learn how to update a component managed via config as code.

At any time, you can disconnect a managed component from config as code and start managing it again from the Compass UI.

Manage a component with config as code

You can manage components that already exist within Compass by adding a compass.yaml file to any git repository in a connected Bitbucket Workspace, GitHub Organization, or GitLab Project. When Compass sees the file committed to your default branch, it will use the data provided in the YAML file to manage the Compass component.

In Compass, view your component's details.
At the top of the Overview page, navigate to Config as code on the left panel.
On this screen you’ll get a pre-formatted compass.yaml file containing the component’s details that are already available in Compass. This is the fastest way to use config as code.
Commit the compass.yaml file to the default branch of your repository.
Refresh the Config as Code page or return to the Overview page and observe that your component is now managed by config as code. It may take a few seconds after you merge your changes for this to take effect.
Update the YAML file to modify component data going forward.

At any time, you can disconnect a managed component from config as code and start managing it again from the Compass UI.

Managing multiple components with config as code in a single repository

You can manage multiple Compass components from a single source code provider repository (i.e. monorepo).

The procedure is the same as managing a single component with config as code, but you must include a separate compass.yaml file for each component and the files must reside in separate subfolders within the repository.

To manage multiple components in a single repository:

Prepare a compass.yaml file for each component. If a component does not yet exist in Compass, you can omit the id field in the YAML file but remember to add it in after the component gets created to ensure proper management.
Add each file to a separate subfolder in your repository and commit them to the repository’s default branch. Each file should be added in a separate commit.
We recommend that you designate each component as part of a monorepo by adding the following lines to your compass.yml file. This will prevent capturing activity (events, metrics) across the entire monorepo with the Bitbucket, GitHub, and GitLab integrations. Send events and metrics for this component using our API.

1
2
fields:
  isMonorepoProject: true

Verify that each component is now a managed component in Compass.

At any time, you can disconnect a managed component from config as code and start managing it again from the Compass UI.

Find a component's ID

Each component in Compass has a unique, unchangeable identifier (ID). Compass assigns each component an ID when you create it. You can find a component's ID on the component's details page in Compass.

If you’re using config as code to manage components, you’ll notice that components are referred to by their unique id in several places in the compass.yaml configuration file. Both the component itself and any other components that it depends on are referred to by their unique IDs. Learn more about the structure and contents of a compass.yaml file

To find a component’s ID:

In Compass, go to a component’s details page. Learn how to view a component's details
Select more actions (•••) then Copy component ID.

The component’s ID is copied to your clipboard.

When using the id in a compass.yaml file, enclose the entire text of the id in single quotes. For example:

1
2
id: 'ari:cloud:compass:00000000-0000-0000-0000-0000:component/0000-0000-0000-0000-000000000000/00000000-0000-0000-0000-0000'

Find a team's owner ID

Each team in Compass has a unique, unchangeable identifier (ID). Compass assigns each team an owner ID when you create it. You can find a team’s owner ID on the team’s dashboard in Compass.

If you’re using config as code to manage components, you’ll notice that teams are referred to by their unique ownerId in the compass.yaml configuration file. Learn more about the structure and contents of a compass.yaml file

To find a team’s owner ID:

In Compass, search for a team to open its dashboard.
Select more actions (•••) then Copy owner ID.

The owner ID is copied to your clipboard.

When using the ownerId in a compass.yaml file, enclose the entire text of the ownerId in single quotes. For example:

1
2
ownerId: 'ari:cloud:teams::team/00000000-0000-0000-0000-000000000000'

Find a single or multi-select custom field's option's ID

Each option of single or multi-select custom field in Compass has a unique, unchangeable identifier (ID).

To find a single or multi-select custom field's option's ID:

If you're using the Compass UI:

In Compass, go to compass settings > custom fields.
Open DevTools of your browser.
Navigate to the Network tab and filter by graphql.
For the custom field you want to use, select More actions and then Edit.
In the DevTools, you'll see a graphql request. Copy the ID of the option from the response of the request you want to use.

If you are using the Compass API:

Make the following request to the Compass API:

1
2
query getCustomFieldDefinitions($query: CompassCustomFieldDefinitionQuery!) {
  compass @optIn(to:"compass-beta"){
    customFieldDefinition(query: $query) {
				... on CompassCustomFieldDefinition {
				__typename
				id

				... on CompassCustomSingleSelectFieldDefinition{
					options {id, value}
				}

				... on CompassCustomMultiSelectFieldDefinition{
					options {id, value}
				}
			}
		}
	}
}

You will get ID of each option in the response