Configuration Reference

Configuration Reference

This section covers all valid configuration file keywords and available settings in detail. The Superblocks configuration file is expected to be named superblocks.yaml, located at the project root directory.

Key Value type Required Description
version String Yes Superblocks configuration file format version
jobs Object Yes A group of one or more jobs
stages Object No A group of stages used to organize the pipeline


Jobs are a required part of a Pipeline. Each job must be an Object referenced by a string and it must contain a set of one or more script lines, together with an optional image reference.

Key Value type Required Description
<job_name> Object Yes The job name identifier
script List Yes A list of command-line strings
services List No A list of service containers to be run, all linked to the provided image
image 1 String No Container image name, reference or full path

The hierarchy is defined as follows:

    - ...
    - ...

[1] When no image is set, the default value is alpine. Alpine Linux is provided as part of the Docker Official Images. See also: Docker Hub.


Stages are an optional part of Pipelines. When no stages are defined, all Jobs are put into a build stage, in no particular order. The default behavior results in no particular execution order, in a way that Jobs can be executed in parallel and out of order.
Each stage must be defined as an List referenced by a string name and it must contain another Object representing the jobs assigned to it. Optionally, it is possible to toggle the allowFailure flag to prevent the pipeline exiting upon job failure, as well as applying filters in order to have the Stages run based on specific conditions.

Key Value type Required Description
<stage_name> List Yes A group of one or more jobs
jobs List Yes The stage jobs group
<job_name> String Yes A reference to a given object
allowFailure 2 Boolean No Allows the pipeline to continue even if the job fails
when 3 String No Marks the job as requiring manual triggering
filters 4 Object No The filters group
only List Yes A list of repository branch names to filter from

The hierarchy is defined as follows:

- <stage_name>:
      - <job_name>:
              - ...

[2] Undefined allowFailure is the same as setting it to false.
[3] The only valid parameter is manual. See also: Introduction to Triggers.
[4] When the filters configuration is not present, the default behavior is to execute the job for all branches without distinction.