Skip to content

Advanced Configuration

Our GitOps configuration suits most common use cases, such as:

  • Single-project per repo
  • Only a single branch needs to be processed for cortex.yaml
  • cortex.yaml in the default or master branch

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

  • Monorepos: multiple projects in a single repo, split into subfolders
  • Branches: Non-master/default branches, or different projects in multiple branches

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 cortex.yaml
  • It should live in the default branch for the repo, regardless of which branches it states Cortex should use to find cortex.yaml 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

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

Documentation

Cortex can embed markdown docs directly in a service's homepage. This feature cannot be combined with the other advanced configuration options.

To display markdown docs in Cortex, add a docs field with a list of directories containing Markdown files to be embedded.

docs:
  - docs
  - wiki