6 minute read

Nyx offers a wide range of configuration options, including:

  • one or more configuration files, available in several grammars
  • command line options
  • environment variables
  • a mix of the above, following a clear evaluation order

All configuration options are available for any of the above methods to let you pick what best suits your needs.

Examples are available for any option and file grammar.

Evaluation order

Options are evaluated in the following order:

  1. command line option
  2. environment variable
  3. plugin settings (Gradle)
  4. custom configuration file that can be set using the configurationFile global option
  5. standard configuration file, in the order:
    1. .nyx.json
    2. .nyx.yaml (or .nyx.yml)
  6. custom shared configuration file that can be set using the sharedConfigurationFile global option
  7. standard shared configuration file, in the order:
    1. .nyx-shared.json
    2. .nyx-shared.yaml (or .nyx-shared.yml)
  8. preset configuration
  9. default value

This means that command line options have priority over all others while default values are only taken into account if no other means is used for a certain option.

Please note that Nyx searches configuration files at standard locations using default names .nyx.yaml (or .nyx.yml), .nyx.json, .nyx-shared.yaml (or .nyx-shared.yml), .nyx-shared.json (pay attention to the leading .) so as long as you use one of these file names and the file is available in the current working directory you don’t need to use the configurationFile option. The file extension reflects the grammar the file must be authored with and if none is available among the ones listed above JSON is assumed by default. If more than one default file is present, they will be evaluated following the above order (.nyx.yaml takes precedence over .nyx.json, while .nyx-shared.yaml takes precedence over .nyx-shared.json).

Since configuration files and environment variables are platform and flavor agnostic they are the suggested way to configure Nyx so that configurations are portable and even usable in combined release processes.

As a rule of thumb, consider using default values and presets before customizing. Defaults are provided for almost all available options and they are engineered to suit the majority of cases. Moreover, there are many entities already modelled as presets (commit message conventions, environments, extra identifiers, release types, services) that you can enable by just using the preset option and may spare you a lot of work.

Since there are so many different ways to configure Nyx, knowing how options are evaluated in the end might be cumbersome. A quick way to see how the final configuration is resolved is by serializing the state file and inspect the configuration element.

When using multiple configuration methods or customizing presets, complex configuration options (like commitMessageConventions, releaseTypes, services, for example) must be inherited or overridden as a whole. Overriding single values and inheriting others is not supported for this type of configuration option so when they are re-declared at one configuration level, all inherited values from those configuration methods with lower precedence are suppressed.

Command line options

When you need to pass a configuration option on the command line you can use the option name listed in the Command Line Option column available in the configuration reference sections.

Some options are available in two forms, the regular one and the short one. For example, bump can be passed both as --bump=<NAME> or -b=<NAME>. In case both are used, the short one has priority.

Other options act as boolean flags so you can explicitly pass a value for them or just set the name and true is assumed. For example, if you want to pass dryRun you can either pass --dry-run=true or simply --dry-run and they will have the same effect. If you want to pass false you need to pass the value as --dry-run=false.

In order to support dynamic argument names, unsupported or malformed arguments are ignored and don’t cause any error.

Environment variables

When you need to pass a configuration option as an environment variable you can use the variable listed in the Environment Variable column available in the configuration reference sections.

Supported file grammars

YAML

simpleOption: "<VALUE>"
section:
    simpleNestedOption: "<VALUE>"
listOption:
    - "<VALUE1>"
    - "<VALUE2>"
    - "<VALUEN>"
objectsListOption:
    -
        option1: "<VALUE1>"
        option2: "<VALUE1>"
    -
        option1: "<VALUE2>"
        option2: "<VALUE2>"
    -
        option1: "<VALUE2>"
        option2: "<VALUE2>"
mapOption:
    <NAME1>: "<VALUE>"
    <NAME2>: "<VALUE>"
    <NAME3>: "<VALUE>"
objectsMapOption:
    <NAME1>:
        option1: "<VALUE2>"
        option2: "<VALUE2>"
    <NAME2>:
        option1: "<VALUE2>"
        option2: "<VALUE2>"
    <NAME3>:
        option1: "<VALUE2>"
        option2: "<VALUE2>"

The grammar definition is available at https://yaml.org/ and you can check the correctness of your YAML files at http://www.yamllint.com/.

JSON

{
    "simpleOption": "<VALUE>",
    "section": {
        "simpleNestedOption": "<VALUE>"
    },
    "listOption": ["<VALUE1>", "<VALUE2>", "<VALUEN>"],
    "objectsListOption": [
        {
            "option1": "<VALUE1>",
            "option2": "<VALUE2>"
        },
        {
            "option1": "<VALUE1>",
            "option2": "<VALUE2>"
        },
        {
            "option1": "<VALUE1>",
            "option2": "<VALUE2>"
        }
    ],
    "mapOption" : {
        "<NAME1>" : "<VALUE>",
        "<NAME2>" : "<VALUE>",
        "<NAME3>" : "<VALUE>"
    },
    "objectsMapOption" : {
        "<NAME1>" : {
            "option1": "<VALUE1>",
            "option2": "<VALUE2>"
        },
        "<NAME2>" : {
            "option1": "<VALUE1>",
            "option2": "<VALUE2>"
        },
        "<NAME3>" : {
            "option1": "<VALUE1>",
            "option2": "<VALUE2>"
        }
    }
}

The grammar definition is available at https://www.json.org/ and you can check the correctness of your JSON files at https://jsonlint.com/.

Gradle

Gradle build scripts can be used to pass options to Nyx by means of extension configuration. To use it just define the extension configuration section in your settings.gradle or build.gradle script like:

nyx {
    simpleOption = '<VALUE>'
    section {
        simpleNestedOption = '<VALUE>'
    }
    listOption = ['<VALUE1>', '<VALUE2>', '<VALUEN>']
    objectsListOption {
        "<NAME1>" {
            option1 = "<VALUE>"
            option2 = "<VALUE>"
        }
        "<NAME2>" {
            option1 = "<VALUE>"
            option2 = "<VALUE>"
        }
        "<NAME3>" {
            option1 = "<VALUE>"
            option2 = "<VALUE>"
        }
    }
    mapOption {
        "<NAME1>" = "<VALUE>"
        "<NAME2>" = "<VALUE>"
        "<NAME3>" = "<VALUE>"
    }
    objectsMapOption {
        "<NAME1>" {
            option1 = "<VALUE>"
            option2 = "<VALUE>"
        }
        "<NAME2>" {
            option1 = "<VALUE>"
            option2 = "<VALUE>"
        }
        "<NAME3>" {
            option1 = "<VALUE>"
            option2 = "<VALUE>"
        }
    }
}

As you can see the entire Nyx configuration is enclosed within the nyx block to isolate it from other options.

Please note that object lists in Gradle DSL are defined just like object maps. Which means you need to give each item a name, even if the object shouldn’t. This is due to a limitation reported here. As a rule of thumb, use the string representation (enclosed in quotes) of the item ordinal for the item name to make sure the order of items is safe.

Gradle build scripts can be authored using the Groovy or the Kotlin grammar.

Collections of objects

Passing configuration options as maps of objects is fairly intuitive when using configuration files, as already shown. On the other hand, passing complex values as command line options or environment variables needs a clear convention.

When passing objects belonging to a list or map we need to intruduce an identifier to refer to an element or another. This identifier can be a simple string, also used as the name attribute. This identifier is represented in this guide as <NAME> (for maps), <#> (for lists) or <ID>.

For example, using the same example as per configuration files, object maps can be passed as command line options as:

--objectMapOption-first-objectOption1=<VALUE>
--objectMapOption-first-objectOption2=<VALUE>
--objectMapOption-second-objectOption1=<VALUE>
--objectMapOption-second-objectOption2=<VALUE>
--objectMapOption-third-objectOption1=<VALUE>
--objectMapOption-third-objectOption2=<VALUE>

The same goes for environment variables, so:

NYX_OBJECT_MAP_OPTION_first_OBJECT_OPTION1=<VALUE>
NYX_OBJECT_MAP_OPTION_first_OBJECT_OPTION2=<VALUE>
NYX_OBJECT_MAP_OPTION_second_OBJECT_OPTION1=<VALUE>
NYX_OBJECT_MAP_OPTION_second_OBJECT_OPTION2=<VALUE>
NYX_OBJECT_MAP_OPTION_third_OBJECT_OPTION1=<VALUE>
NYX_OBJECT_MAP_OPTION_third_OBJECT_OPTION2=<VALUE>

Names in identifiers must be considered case sensitive. Moreover, item names must not contain whitespaces or characters other than alphanumeric.

Object lists can be passed as command line options as:

--objectListOption-1-objectOption1=<VALUE>
--objectListOption-1-objectOption2=<VALUE>
--objectListOption-2-objectOption1=<VALUE>
--objectListOption-2-objectOption2=<VALUE>
--objectListOption-3-objectOption1=<VALUE>
--objectListOption-3-objectOption2=<VALUE>

The same goes for environment variables, so:

NYX_OBJECT_LIST_OPTION_1_OBJECT_OPTION1=<VALUE>
NYX_OBJECT_LIST_OPTION_1_OBJECT_OPTION2=<VALUE>
NYX_OBJECT_LIST_OPTION_2_OBJECT_OPTION1=<VALUE>
NYX_OBJECT_LIST_OPTION_2_OBJECT_OPTION2=<VALUE>
NYX_OBJECT_LIST_OPTION_2_OBJECT_OPTION1=<VALUE>
NYX_OBJECT_LIST_OPTION_2_OBJECT_OPTION2=<VALUE>

Ordinals can be positive integers only and must not contain whitespaces or characters other than numeric. The ordinal used determines the order of elements. The first ordinal is 0.