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` and `jbang`.
    # 
    gav: com.acme:my-jreleaser-extension:1.2.3

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

    # JBang script.
    # Mutually exclusive with `gav` and `directory`.
    # 
    jbang:
      # JBang script reference to use.
      # Any reference that produces a JAR file can be used.
      # i.e. local or remote .java, .kt, .groovy, .jar or file,
      # a GAV or a jbang-catalog reference.
      # 
      script: src/jreleaser-ext/my-jreleaser-extension.java

      # JBang version to launch the script.
      # 
      version: 0.128.5

    # 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` and `jbang`.
  # 
  directory = "path/to/my-jreleaser-extension/jars"

  # JBang script.
  # Mutually exclusive with `gav` and `directory`.
  # 

  # JBang script reference to use.
  # Any reference that produces a JAR file can be used.
  # i.e. local or remote .java, .kt, .groovy, .jar or file,
  # a GAV or a jbang-catalog reference.
  # 
  jbang.script = "src/jreleaser-ext/my-jreleaser-extension.java"

  # JBang version to launch the script.
  # 
  jbang.version = "0.128.5"

  # 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` and `jbang`.
      // 
      "directory": "path/to/my-jreleaser-extension/jars",

      // JBang script.
      // Mutually exclusive with `gav` and `directory`.
      // 
      "jbang": {
        // JBang script reference to use.
        // Any reference that produces a JAR file can be used.
        // i.e. local or remote .java, .kt, .groovy, .jar or file,
        // a GAV or a jbang-catalog reference.
        // 
        "script": "src/jreleaser-ext/my-jreleaser-extension.java",

        // JBang version to launch the script.
        // 
        "version": "0.128.5"
      },

      // 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>

      <!--
        JBang script.
        Mutually exclusive with `gav` and `directory`.
        
      -->
      <jbang>
        <!--
          JBang script reference to use.
          Any reference that produces a JAR file can be used.
          i.e. local or remote .java, .kt, .groovy, .jar or file,
          a GAV or a jbang-catalog reference.
          
        -->
        <script>src/jreleaser-ext/my-jreleaser-extension.java</script>

        <!--
          JBang version to launch the script.
          
        -->
        <version>0.128.5</version>
      </jbang>

      <!--
        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` and `jbang`.
      // 
      directory = 'path/to/my-jreleaser-extension/jars'

      // JBang script.
      // Mutually exclusive with `gav` and `directory`.
      // 
      jbang {
        // JBang script reference to use.
        // Any reference that produces a JAR file can be used.
        // i.e. local or remote .java, .kt, .groovy, .jar or file,
        // a GAV or a jbang-catalog reference.
        // 
        script = 'src/jreleaser-ext/my-jreleaser-extension.java'

        // JBang version to launch the script.
        // 
        version = '0.128.5'
      }

      // 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 in the same directory or subdirectory as 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
│   └── lib/other.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.

JBang

jbang provides an alternative to gav and directory for loading extensions.

JBang allows you to reference any resource that JBang can execute, including local and remote JAR files, GAV coordinates, and scripts. When using scripts, you can point to local source files that will be automatically compiled and packaged, providing a convenient way to extend JReleaser without additional project setup.

Do not configure gav, directory, or jbang simultaneously. These properties are mutually exclusive.