Environment

JReleaser can configure some of its fields from external sources. This allows keeping a stable configuration file and only update the external sources to produce a new release. Values may be read from a Java properties file or from environment variables, the file has precendence over the environment variables.

By default, the external properties file should be located at $HOME/.jreleaser/config.properties however you may change that location by setting/changing the value of the JRELEASER_USER_HOME environment variable or using the block described in the next section.

On platforms that support the XDG-spec JReleaser will check $XDG_CONFIG_HOME/jreleaser before $JRELEASER_USER_HOME.

Configuration

Legend:

  • required

  • optional

  • may use environment variable

  • accepts Name Templates

  • YAML

  • TOML

  • JSON

  • Maven

  • Gradle

# Configures environment sources.
# 
environment:

  # Location of a properties file with key/value pairs
  # Each key must be prefixed with `JRELEASER_` and match
  # the environment variable it overrides.
  # 
  variables: path/to/alternate/config.properties

  # Additional properties used when evaluating templates.
  # 
  properties:
    foo: bar
# Configures environment sources.
# 
[environment]

  # Location of a properties file with key/value pairs
  # Each key must be prefixed with `JRELEASER_` and match
  # the environment variable it overrides.
  # 
  variables = "path/to/alternate/config.properties"

  # Additional properties used when evaluating templates.
  # 
  properties.foo = "bar"
{
  // Configures environment sources.
  // 
  "environment": {
    // Location of a properties file with key/value pairs
    // Each key must be prefixed with `JRELEASER_` and match
    // the environment variable it overrides.
    // 
    "variables": "path/to/alternate/config.properties",

    // Additional properties used when evaluating templates.
    // 
    "properties": {
      "foo": "bar"
    }
  }
}
<jreleaser>
  <!--
    Configures environment sources.
    
  -->
  <environment>
    <!--
      Location of a properties file with key/value pairs
      Each key must be prefixed with `JRELEASER_` and match
      the environment variable it overrides.
      
    -->
    <variables>path/to/alternate/config.properties</variables>

    <!--
     Additional properties used when evaluating templates.
     
    -->
    <properties>
      <foo>bar</foo>
    </properties>
  </environment>
</jreleaser>
jreleaser {
  // Configures environment sources.
  // 
  environment {
    // Location of a properties file with key/value pairs
    // Each key must be prefixed with `JRELEASER_` and match
    // the environment variable it overrides.
    // 
    variables = 'path/to/alternate/config.properties'

    // Additional properties used when evaluating templates.
    // 
    properties.put('foo', 'bar')
  }
}

Formats currently supported for the file configurable in the variables field are:

  • .properties

  • .yml

  • .toml

  • .json

  • PROPERTIES

  • YAML

  • TOML

  • JSON

config.properties
JRELEASER_GITHUB_TOKEN = b9df0920aefcbfa69f57c4f02bae4396
config.yml
JRELEASER_GITHUB_TOKEN: b9df0920aefcbfa69f57c4f02bae4396
config.toml
JRELEASER_GITHUB_TOKEN = "b9df0920aefcbfa69f57c4f02bae4396"
config.json
{
  "JRELEASER_GITHUB_TOKEN": "b9df0920aefcbfa69f57c4f02bae4396"
}
The config file must use the appropriate file extension that matches the format in use.
The config file should have key/value pairs with no nesting. Each key maps to the corresponding environment variable that requires a value.
Use the yml or toml formats for key/values that require multiple lines, such as JRELEASER_GPG_PUBLIC_KEY.

When using a format that supports multi-line strings be sure to follow these rules:

Yaml

  • Use a | as the sole character of the first line.

  • Indent every other line, typically with 2 spaces.

Toml

  • Do not indent lines unless the indentation must be part of the content.

As an example, the JRELEASER_GPG_PUBLIC_KEY key/value may be written as follows:

  • YAML

  • TOML

config.yml
JRELEASER_GPG_PUBLIC_KEY: |
  -----BEGIN PGP PUBLIC KEY BLOCK----

  mQGiBEYVIwERBACndCqn1kKjVD8r2YjYAsqzNQet/U7wn6pIrvKd+23W+LH04tRY
  ...
  -----END PGP PUBLIC KEY BLOCK-----
config.toml
JRELEASER_GPG_PUBLIC_KEY="""-----BEGIN PGP PUBLIC KEY BLOCK----

mQGiBEYVIwERBACndCqn1kKjVD8r2YjYAsqzNQet/U7wn6pIrvKd+23W+LH04tRY
...
-----END PGP PUBLIC KEY BLOCK-----"""

Take special note that the empty line at the 2nd row is required, otherwise you may get an error similar to the following one:

Caused by: http://java.io.IOException: public key ring doesn't start with public key tag: tag 0xffffffff

Maven

JReleaser will honor Maven project properties. These properties can be defined in several ways:

  • on the command line by using the -D flag.

  • on a pom.xml by using the <properties> block.

  • on a settings file using the <properties> block inside an active profile.

JReleaser should be able to handle properties define in any of these ways. Precedence is:

  • values defined in the model.

  • values defined as Maven properties.

  • values defined in <releaser><environment><variables>.

  • environment variables.

Keys must either be fully uppercase words separated by underscores (_) or fully lowercase words separated by dots (.). The uppercase variant has precedence over the lowercase variant. For example, the Github token may be defined in ~/.m2/settings.xml as:

settings.xml
<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0
                      https://maven.apache.org/xsd/settings-1.0.0.xsd">

    <profiles>
      <profile>
        <id>jreleaser</id>
        <activation>
          <activeByDefault>true</activeByDefault>
        </activation>
        <properties>
          <JRELEASER_GITHUB_TOKEN>2ee1ce8ff570e0bOVEdrZvie8792058</JRELEASER_GITHUB_TOKEN>
        </properties>
      </profile>
    </profiles>
</settings>

Or as

settings.xml
<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0
                      https://maven.apache.org/xsd/settings-1.0.0.xsd">

    <profiles>
      <profile>
        <id>jreleaser</id>
        <activation>
          <activeByDefault>true</activeByDefault>
        </activation>
        <properties>
          <jreleaser.github.token>2ee1ce8ff570e0bOVEdrZvie8792058</jreleaser.github.token>
        </properties>
      </profile>
    </profiles>
</settings>

Gradle

JReleaser will honor Gradle project properties. These properties can be defined in several ways:

  • on the command line by using the -P flag.

  • on a gradle.properties file adjacent to the project.

  • on a gradle.properties file located at ~/.gradle.

JReleaser should be able to handle properties define in any of these ways. Precedence is: - values defined in the model. - values defined as Gradle project properties. - values defined in jreleaser.environment.variables. - environment variables.

Keys must either be fully uppercase words separated by underscores (_) or fully lowercase words separated by dots (.). The uppercase variant has precedence over the lowercase variant. For example, the Github token may be defined in /.gradle/gradle.properties as:

gradle.properties
JRELEASER_GITHUB_TOKEN = 2ee1ce8ff570e0bOVEdrZvie8792058

Or as:

gradle.properties
jreleaser.github.token = 2ee1ce8ff570e0bOVEdrZvie8792058

.env Files

This format is similar to the .properties format described earlier.

.env
JRELEASER_GITHUB_TOKEN = b9df0920aefcbfa69f57c4f02bae4396

.env files must be placed at the basedir of the project, must be named .env, and there can only be a single file.

Precedence Order

Settings will be evaluated in the following order:

  • Explicitly set in the corresponding DSL.

  • Defaults coming from the build tool (maven Maven, gradle Gradle).

  • Command flags.

  • System properties.

  • The running shell’s environment variables.

  • Project configuration (.env file).

  • User configuration ($XDG_CONFIG_HOME/jreleaser, $JRELEASER_USER_HOME, $HOME/.jreleaser).

Inspection

Use the env command to display environment variable key names as resolved by the tool

You’ll also find these key names in the respective trace.log file.