The Cider-CI Configuration File
- Accepted Formats
- Getting Started
- Canonical Syntax versus Compact Notation
- Validation of the Specification
- Reserved Keywords
- Where to go from here
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.
Cider-CI will look for the following files to read the configuration:
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.
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.
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.
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.
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.
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.
include and any keyword starting with
_cider-ci is reserved and may not be used.