Last updated Apr 26, 2024

What is configuration 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.

Why should I sync a component?

With config as code, you move the source of truth for Compass component data to a compass.yaml configuration file in your code repository. Any updates to the YAML file on your repository’s default branch automatically sync back to and reflect in Compass.

You can also create new components by simply committing a compass.yaml to a git repository.

Some of the benefits of config as code are:

Manage your component via YAML right next to your source code without needing to navigate to the UI.
Governance, via repository permissions & settings, over who can update component catalog information.
Version control of your component metadata.
Update your compass.yaml files with scripts or build jobs to help keep information fresh.

What tools can I use to manage synced components?

Compass currently supports config as code with Bitbucket Cloud, GitHub Cloud, and GitLab.com.

How does config as code work?

To set up config as code, a Compass admin must first install and configure one of the above mentioned source code management apps in Compass.

Then, in your git repository, declare a component’s details in a YAML configuration file called compass.yaml or compass.yml. Each component should have its own compass.yaml file. Learn more about the structure and contents of a compass.yaml file.

Set up config as code for your component by committing the compass.yaml file to the default branch (i.e. main or master usually) in your repository. Learn how to manage components with config-as-code.
When you commit your changes to the default branch of your repository, the component connects to the repository from where you’ll manage it.
If the component does not exist yet, Compass will automatically create the component and associate it with the repository when a compass.yaml file is committed.
You can also manage multiple Compass components from the same repository. Place the compass.yaml files in separate subfolders anywhere in your repository structure. This is helpful if you have a monorepo.

While it is possible to add multiple repository links to a component, config-as-code will only handle the first link added, as events and data connections may not function properly for the additional links. To prevent this, we recommend making sure only a single repository link is connected so that config-as-code works as expected.

Once you set up config as code for a component, the compass.yaml file in your repository becomes the source of truth for all the component’s details. You now manage the component by making changes only in the compass.yaml file, not via the Compass UI or API.

When you commit the changes to your repository’s default branch, the changes automatically sync back to Compass and reflect in your component’s details.
You can update a component’s details by making changes in the compass.yaml file. Learn how to update a component managed via config as code
At any time, you can disconnect a managed component from config as code by simply deleting the yaml file.