1. Home
  2. Project Configuration
  3. Configuration File

The Cider-CI Configuration File

Cider-CI reads the specification to create and run jobs from a file in the top level directory of your project. This page gives an introduction how to write a Cider-CI project file. The more formal Cider-CI Project Specification lists all available keys and configuration options of Cider-CI.

Filenames

Cider-CI will look for the following files to read the configuration:

  1. cider-ci_v4.yml,
  2. .cider-ci_v4.yml,
  3. cider-ci_v4.json,
  4. .cider-ci_v4.json,
  5. cider-ci.yml,
  6. .cider-ci.yml,
  7. cider-ci.json, and
  8. .cider-ci.json.

The first file found will be used and any further will be ignored. The Cider-CI User Interface will show a warning if none of the possible configuration files have been found.

Accepted Formats

As indicated by the extension of the files Cider-CI accepts either YAML or JSON format. YAML is technically a superset of JSON, by capability and syntax. Cider-CI uses only features of YAML which can be presented in JSON. We prefer to use YAML for examples in this documentation.

Getting Started

The example specifies one job with one task and inside a very simple script. It exits with status 0 which indicates that the script has passed. The script itself is written so it will work with under either Linux, Mac OS, or Windows.

1jobs:
2  introduction-demo:
3    name: Introduction Demo and Example Job
4    description: |
5      A very concise job declaration which uses the compact notation.
6    task: |
7      :; exit 0
8      exit /b 0

Canonical Syntax versus Compact Notation

The previous example is written in compact notation. The compact notation is short and easy to read. However, many configuration options can not be expressed in compact notation and thus only simple jobs can be written in this format.

Internally Cider-CI converts the compact notation into its canonical syntax before evaluating it. The same configuration in canonical syntax would read like the example given here.

 1jobs:
 2  introduction-demo:
 3    key: introduction-demo
 4    name: Introduction Demo and Example Job
 5    description: A very concise job declaration which uses the compact notation.
 6    context:
 7      tasks:
 8        '0':
 9          scripts:
10            main:
11              body: |
12                :; exit 0
13                exit /b 0

Validation of the Specification

Much of what is happening inside Cider-CI adheres to the fail-fast principle. To that end Cider-CI has a validator which will parse the project configuration. It will show a warnings and prevent any execution when it encounters unspecified keys, if values are of wrong type, or if they can not be parsed.

On the one hand the validator might feel annoying at times. But we believe that such a rigorous validation is a very important quality of a CI system. In the end it lets you write your configuration faster and more efficient since it frees you from double and triple checking it.

Reserved Keywords

The keywords of the maps used in the Cider-CI configuration play important roles. In the case of a job the keyword is used to identify a job uniquely and reference it when declaring dependencies for example. Those keywords may be chosen freely with a few exceptions.

The keyword include and any keyword starting with _cider-ci is reserved and may not be used.

Where to go from here

The more formal Cider-CI Project Specification lists all available keys and configuration options of Cider-CI. The data flow page describes the transformations applied to the configuration file.