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. You can choose to declare component details in a YAML file that sits alongside the source code for the component itself. Learn more about how config as code works

Compass currently supports config as code with Bitbucket Cloud, GitHub Cloud, and GitLab.com. After integrating Compass with a source code provider, you can set up config as code for a component existing in Compass by declaring its details in a compass.yaml file that lives in the source repository. Any updates to the compass.yaml 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 a component existing in Compass 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:

• Create your component in Compass or import it from other apps. Before setting up config as code for a component, you must first create it in Compass.

• Install and configure a source code provider app for Compass. You must be an admin of the source code provider workspace/organization and your Compass site to perform this step.

• Verify that you can access the source code provider workspace/organization configured for Compass and you have read and write permissions on the repositories within that source code provider.

• Have some basic experience with using Git and familiarize yourself with adding and editing files in Bitbucket Cloud or GitHub. Learn how to add, edit, and commit to source files in a Bitbucket repository or learn how to manage files in GitHub

• Have a basic understanding of YAML file structures.

• Familiarize yourself with the structure and contents of the compass.yml file.

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.yaml file.
2. Add the compass.yaml file to your repository in your source code provider and commit your changes to the default branch.
3. Verify your managed component in Compass.

Step 1: Prepare your compass.yaml file

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

To prepare the compass.yaml file:

1. In Compass, view your component's details.
2. At the top of the Overview page, on the Manage this component with compass.yaml card, select Set up.
   • You’ll get a pre-formatted compass.yaml file containing the component’s details that are already available in Compass.
   • If you have not already installed and configured a source code provider app, the card prompts you to complete the integration. Come back here once you've completed the app installation.
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.yaml file.

Step 2: Add the compass.yaml file to your repository in your source code provider

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

To add the compass.yaml file to your repository in your source code provider:

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

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.yaml file in your source code provider. 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.yaml file reflects correctly in the component’s details in Compass.

   • Notice that now there's a Managed by compass.yaml in {name of source code provider} description under the component name.

3. Select Component settings in the left side menu.

4. Select Go to compass.yaml. The compass.yaml file in the repository opens.

5. Verify that the link between the component and its corresponding compass.yaml file is correct.

Your component is now managed with config as code.

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.

Managing multiple components with config as code in a single repository

You can manage multiple Compass components from a single source code provider repository.

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:

1. Prepare a compass.yaml 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 repository and merge your changes to the repository’s default branch.
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.yaml 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.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:

1. In Compass, go to a component’s details page. Learn how to view a component's details
2. 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:

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