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.

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'
        ]
      }
    }
  }
}

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.