Skip to main content

Advanced configuration

Our out-of-the-box GitOps configuration suits most common use cases, such as:

  • Single or many projects per repo
  • Only a single branch needs to be processed for cortex.yaml
  • Your cortex.yaml is in the default or master branch

However, there may be scenarios that require special setups, including:

  • Monorepos in Bitbucket: multiple projects in a single repo, split into subfolders
  • Branches: Non-master/default branches, or different projects in multiple branches
Monorepos in GitHub and GitLab are supported by default

You don't need to set up the following cortex-properties.yaml if using a monorepo with many cortex.yaml files throughout a single repository, when integrating with GitHub or GitLab, as this is supported out of the box. Cortex will discover any Catalog Descriptor files in your repository, regardless of where in the folder structure they're located.

You only need to use a cortex-properties.yaml file if using monorepos in Bitbucket, or want to use a non-default branch as the home for your Catalog Descriptor files.

To account for these use cases, you can "configure" Cortex by telling us how to process events from your repo.

cortex-properties.yaml​

The configuration for a repository lives in a cortex-properties.yaml file.

Don't use this if you don't need advanced configuration!

This file is optional and should only be used if you have a custom workflow.

Some details about this file:

  • Inclusion of this file in your repo is fully optional
  • The file is automatically processed, just like the Catalog Descriptor
  • It should live in the default branch for the repo, regardless of which branches it states Cortex should use to find Catalog Descriptor files.

Branches​

You can configure Cortex to automatically process cortex.yaml files in non-standard branches, multiple branches, or both. Imagine the scenario:

  1. You have a project where master is protected, but the default branch
  2. You want to include cortex.yaml in the develop branch
  3. You also have a separate version of the project in the staging branch, with its own cortex.yaml file.

To represent this, you would add a cortex-properties.yaml file in the default branch of your repo, with a list of branches to process.

branches:
  - master
  - develop
  - staging
Default branch must be explicitly defined if using advanced configuration

If using the branches field in your cortex-properties.yaml file, AND you want Cortex to continue looking for a cortex.yaml file in the master (or other default branch), it MUST be included in this list.

If your cortex-properties.yaml file does not contain a branches field, Cortex will continue to process the default branch.

Source directories​

You can configure Cortex to look for cortex.yaml files in multiple subdirectories. Consider the scenario:

  1. You have a monorepo structure, where all projects live in a single repository
  2. Each project lives in a subdirectory in the main repository (project1/, project2/, etc.)
  3. Each project has its own cortex.yaml file.

To represent this, you would add a src-dirs field in a cortex-properties.yaml file at the root of the repository, containing a list of directories to process.

src-dirs:
  - project1
  - project2

Cortex will still process any cortex.yaml file found in the root of the repository.