Extensions

Extensions let you customize specific aspects of the release process with your own implementations.

If you’re interested in writing your own extensions then refer to this page.

Configuration

Legend:

  • required

  • optional

  • may use environment variable

  • accepts Name Templates

  • YAML

  • TOML

  • JSON

  • Maven

  • Gradle

# 
extensions:

  # Extensions need a name.
  # 
  my-extension:

    # Whether the extension is enabled or not.
    # Defaults to `true`.
    #  
    enabled: true

    # Maven GAV coordinates used to resolve JARs.
    # Mutually exclusive with `directory`.
    # 
    gav: com.acme:my-jreleaser-extension:1.2.3

    # Directory where JARs are located.
    # Mutually exclusive with `gav`.
    # 
    directory: path/to/my-jreleaser-extension/jars

    # Customize extension providers individually.
    # 
    providers:
        # Fully qualified class name.
        # 
      - type: com.acme.MyJReleaserExtensionPoint
        # Additional properties required during provider initialization.
        # 
        properties:
          key: value
# Extensions need a name.
# 
[extensions.my-extension]
  # Whether the extension is enabled or not.
  # Defaults to `true`.
  #  
  enabled = true

  # Maven GAV coordinates used to resolve JARs.
  # Mutually exclusive with `directory`.
  # 
  gav = "com.acme:my-jreleaser-extension:1.2.3"

  # Directory where JARs are located.
  # Mutually exclusive with `gav`.
  # 
  directory = "path/to/my-jreleaser-extension/jars"

  # Customize extension providers individually.
  # 
[[extensions.my-extension.providers]]
  # Fully qualified class name.
  # 
  type = "com.acme.MyJReleaserExtensionPoint"
  # Additional properties required during provider initialization.
  # 
  properties.key = "value"
{
  // 
  "extensions": {
    // Extensions need a name.
    //  
    "my-extension": {

      // Whether the extension is enabled or not.
      // Defaults to `true`.
      // 
      "enabled": true,

      // Maven GAV coordinates used to resolve JARs.
      // Mutually exclusive with `directory`.
      // 
      "gav": "com.acme:my-jreleaser-extension:1.2.3",

      // Directory where JARs are located.
      // Mutually exclusive with `gav`.
      // 
      "directory": "path/to/my-jreleaser-extension/jars",

      // Customize extension providers individually.
      // 
      "providers": [
        {
          // Fully qualified class name.
          // 
          "type": "com.acme.MyJReleaserExtensionPoint",
          // Additional properties required during provider initialization.
          // 
          "properties": {
            "key": "value"
          }
        }
      ]
    }
  }
}
<jreleaser>
  <!--
    
  -->
  <extensions>
    <!--
      Extensions need a name.
      
    -->
    <my-extension>

      <!--
        Whether the extension is enabled or not.
        Defaults to `true`.
         
      -->
      <enabled>true</enabled>

      <!--
        Maven GAV coordinates used to resolve JARs.
        Mutually exclusive with `directory`.
        
      -->
      <gav>com.acme:my-jreleaser-extension:1.2.3</gav>

      <!--
        Directory where JARs are located.
        Mutually exclusive with `gav`.
        
      -->
      <directory>path/to/my-jreleaser-extension/jars</directory>

      <!--
        Customize extension providers individually.
        
      -->
      <providers>
        <provider>

          <!--
            Fully qualified class name.
            
           -->
          <type>com.acme.MyJReleaserExtensionPoint</type>
          <!--
            Additional properties required during provider initialization.
            
           -->
          <properties>
            <key>value</key>
          </properties>
        </provider>
      </providers>
    </my-extension>
  </extensions>
</jreleaser>
jreleaser {
  // 
  extensions {
    // Extensions need a name.
    // 
    my-extension {

      // Whether the extension is enabled or not.
      // Defaults to `true`.
      //  
      enabled = true

      // Maven GAV coordinates used to resolve JARs.
      // Mutually exclusive with `directory`.
      // 
      gav = 'com.acme:my-jreleaser-extension:1.2.3'

      // Directory where JARs are located.
      // Mutually exclusive with `gav`.
      // 
      directory = 'path/to/my-jreleaser-extension/jars'

      // Customize extension providers individually.
      // 
      provider {
        // Fully qualified class name.
        // 
        type = 'com.acme.MyJReleaserExtensionPoint'
        // Additional properties required during provider initialization.
        // 
        properties = [
          key: 'value'
        ]
      }
    }
  }
}

Environment

When not explicitly set, the value of the following properties may be resolved from an environment variable or a system property as shown in the table. The system property takes precedence over the environment variable.

System Property Environment Variable

enabled

jreleaser.extensions.${name}.enabled

JRELEASER_EXTENSIONS_${name}_ENABLED
Substitute ${name} for the value of the named instance.

Space (' '), underscore (_), and dash (-) will be replaced by dot (.) to separate tokens in the System property. Space (' '), dash (-), and dot (.) will be replaced by underscore (_) to separate tokens in the environment variable, such that:

${name} System Property Environment Variable

foobar

foobar

FOOBAR

fooBar

foobar

FOOBAR

foo bar

foo.bar

FOO_BAR

foo-bar

foo.bar

FOO_BAR

foo_bar

foo.bar

FOO_BAR

foo.bar

foo.bar

FOO_BAR

Packaging

Extensions should be packaged as JAR files. If the extension has additional dependencies then those JARs may be placed next to the extension JAR or the extension may be repackaged as an uberjar or fatjar.

Do not shade nor bundle JReleaser classes with your extension.

Directory

The default location to place extensions is ${JRELEASER_USER_HOME}/extensions/<extension-name>. This location may be changed by setting the directory property of the matching named extension. Here are some examples:

An extension named foo with JAR file foo-1.0.0.jar may be placed at ${JRELEASER_USER_HOME}/extensions/foo.
An extension named bar with JAR file bar-2.0.0.jar and dependencies may be placed at ${JRELEASER_USER_HOME}/extensions/bar.

${JRELEASER_USER_HOME}/extensions/
├── bar
│   ├── bar-2.0.0.jar
│   └── guava-31.1-jre.jar
└── foo
    └── foo-1.0.0.jar

GAV

As an alternative to explicitly placing extension JARs at a given location, JReleaser may download the extension JAR (plus any dependencies it may have) from a Maven compatible repository.

Do not configure gav and directory at the same time. These properties are mutually exclusive to each other.