Last updated Sep 6, 2021

Rate this page:

Manage components with config as code

Configuration as code (config-as-code) is an automated method of maintaining Compass component data in a Git repository. When you use this method, you declare component details in a YAML file that sits alongside the source code for the component itself.

Compass currently supports config-as-code with Bitbucket Cloud. After integrating Compass with Bitbucket, you can set up config-as-code for a component by declaring its details in a compass.yml file that lives in the source repository. Any updates to the compass.yml on your repository’s default branch automatically sync back and are reflected in Compass. The component becomes a managed component.

Here, we’ll take you through the process of setting up config-as-code for one component and also show you how you can manage multiple components from the same repository.

Before you begin

Before you set up config-as-code, make sure you’ve done the following:

Manage a component with config-as-code

Managing a component with config-as-code requires you to perform the following steps:

  1. Prepare the compass.yml file.
  2. Add the compass.yml file to your repository in Bitbucket and commit your changes to the default branch.
  3. Verify your managed component in Compass.

Step 1: Prepare your compass.yml file

The first step to manage a component via config-as-code is to prepare the compass.yml configuration file.

To prepare the compass.yml file:

  1. In Compass, view your component's details.
  2. In the right sidebar, on the Manage this component with compass.yml card, select Set up compass.yml.
    • You’ll get a pre-formatted compass.yml file containing the component’s details that are already available in Compass.
    • If you have not already installed and configured the Bitbucket Cloud app, the card prompts you to complete the integration. Come back here once you've completed the integration of Compass with Bitbucket Cloud.
  3. Select Download and save the file to your local machine.
    • You can also copy the contents to your clipboard and manually create the compass.yml file.

Step 2: Add the compass.yml file to your repository in Bitbucket

After you prepare your compass.yml file, the next step is to add it to your repository and merge the changes with the default branch.

To add the compass.yml file to your repository in Bitbucket:

  1. Add the compass.yml file to the component’s repository.
    • You can place the file anywhere within the repository.
  2. Push the changes to Bitbucket and open a pull request if necessary.
  3. Merge the changes to your repository’s default branch in Bitbucket.

Step 3: Verify your managed component in Compass

The last step is to verify that your component in Compass is managed via config-as-code.

To verify your managed component in Compass:

  1. In Compass, reload the component’s details page.

    • You’ll notice that you can no longer update the component details from the Compass UI, which means your component is now managed with the compass.yml file in Bitbucket. It may take a few seconds after you merge your changes for this to take effect.
    • 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
  2. Verify that the information from the compass.yml file reflects correctly in the component’s details in Compass.

  3. Notice that the right sidebar now has a Component manager card.
    • This card shows that the component is managed with the compass.yml file and links directly to the file in its repository.
  4. On the Component manager card, select Go to source. The compass.yml file in the Bitbucket repository opens.
  5. Verify that the link between the component and its corresponding compass.yml file is correct.

Your component is now managed with config-as-code.

From here onwards, every time you update the compass.yml 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.

Managing multiple components with config-as-code in a single repository

You can manage multiple Compass components from a single Bitbucket repository.

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

To manage multiple components in a single repository:

  1. Prepare a compass.yml file for each component. Learn how to prepare the file
    • Make sure that each file has a unique component id, which distinguishes one file from another and connects them to the correct components in Compass.
  2. Add each file to a separate subfolder in your Bitbucket repository and merge your changes to the repository’s default branch in Bitbucket. Learn how to add a compass.yml file to the Bitbucket repository
  3. Verify that each component is now a managed component in Compass. Learn how to verify your managed component in Compass
    • Make sure that each component links to the same repository and opens its own compass.yml file from its respective subfolder.
    • 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

From here onwards, you can update a component managed with 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.

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.yml 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.yml file

To find a component’s ID:

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

The component’s ID is copied to your clipboard.

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

1
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.yml configuration file. Learn more about the structure and contents of a compass.yml file

To find a team’s owner ID:

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

The owner ID is copied to your clipboard.

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

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

Rate this page: