Command Hooks

Defines command hooks to be executed before or after a JReleaser step.

Configuration

Legend:

  • required

  • optional

  • may use environment variable

  • accepts Name Templates

  • YAML

  • TOML

  • JSON

  • Maven

  • Gradle

# 
hooks:
  # Enable or disable all hooks.
  # Supported values are [`NEVER`, `ALWAYS`, `RELEASE`, `SNAPSHOT`].
  # Defaults to `ALWAYS`.
  #  
  active: ALWAYS

  # Execute hooks if the condition evaluates to `true`.
  #  
  condition: '"{{ Env.CI }}" == true'

  # A map of global environment variables.
  # Accepts values from `matrix`.
  #  
  environment:
    FOO: bar

  # Includes the default matrix.
  # 
  applyDefaultMatrix: false

  # Configures matrix variables.
  # 
  matrix:
    vars:
      os: [ linux, osx, windows ]
      arch: [ arm64, amd64 ]
    rows:
      - { os: linux, arch: arm64 }
      - { os: linux, arch: amd64 }
      - { os: osx, arch: arm64 }
      - { os: osx, arch: amd64 }
      - { os: windows, arch: arm64 }
      - { os: windows, arch: amd64 }

  # 
  command:
    # Enable or disable all before, success, and failure hooks.
    # Supported values are [`NEVER`, `ALWAYS`, `RELEASE`, `SNAPSHOT`].
    # Defaults to `ALWAYS`.
    #  
    active: ALWAYS

    # Execute commands if the condition evaluates to `true`.
    #  
    condition: '"{{ Env.CI }}" == true'

    # A map of command environment variables.
    # Accepts values from `matrix`.
    #  
    environment:
      FOO: bar

    # Includes the default matrix.
    # 
    applyDefaultMatrix: false

    # Configures matrix variables.
    # Values will be inherited from `hooks`.
    # 
    matrix:
      vars:
        os: [ linux, osx, windows ]
        arch: [ arm64, amd64 ]
      rows:
        - { os: linux, arch: arm64 }
        - { os: linux, arch: amd64 }
        - { os: osx, arch: arm64 }
        - { os: osx, arch: amd64 }
        - { os: windows, arch: arm64 }
        - { os: windows, arch: amd64 }

    # The type of hook
    # Valid entries are `before`, `success`, `failure`.
    # 
    before:
        # Let the release continue if the hook fails.
        # Defaults to `false`.
        # 
      - continueOnError: true

        # Print command out/err to log.
        # Defaults to `false`.
        # 
        verbose: true

        # Enable or disable this hook.
        # Supported values are [`NEVER`, `ALWAYS`, `RELEASE`, `SNAPSHOT`].
        # Defaults to `ALWAYS`.
        #  
        active: ALWAYS

        # A map of local environment variables.
        # Accepts values from `matrix`.
        #  
        environment:
          FOO: bar

        # Includes the default matrix.
        # 
        applyDefaultMatrix: false

        # Configures matrix variables.
        # Values will be inherited from `command`.
        # 
        matrix:
          vars:
            os: [ linux, osx, windows ]
            arch: [ arm64, amd64 ]
          rows:
            - { os: linux, arch: arm64 }
            - { os: linux, arch: amd64 }
            - { os: osx, arch: arm64 }
            - { os: osx, arch: amd64 }
            - { os: windows, arch: arm64 }
            - { os: windows, arch: amd64 }

        # Execute the command if the condition evaluates to `true`.
        #  
        condition: '"{{ Env.CI }}" == true'

        # The command to be invoked.
        # Accepts values from `matrix`.
        #  
        cmd: '{{basedir}}/notifier.sh {{event.name}} {{event.type}} {{projectVersion}}'

        # Filters this hook based on the given step.
        # 
        filter:
          includes: ['release']
          excludes: ['publish']

        # Filters this hook based on the current platform.
        # Use a `!` prefix to exclude a platform
        # 
        platforms:
          - linux
          - !windows
# 
[hooks]
  # Enable or disable all hooks.
  # Supported values are [`NEVER`, `ALWAYS`, `RELEASE`, `SNAPSHOT`].
  # Defaults to `ALWAYS`.
  #  
  active = "ALWAYS"

  # Execute hooks if the condition evaluates to `true`.
  #  
  condition = "'{{ Env.CI }}' == true"

  # A map of global environment variables.
  # Accepts values from `matrix`.
  #  
  environment.FOO = "bar"

  # Includes the default matrix.
  # 
  applyDefaultMatrix = false

  # Configures matrix variables.
  # 
  matrix.vars.os = [ "linux", "osx", "windows" ]
  matrix.vars.arch= [ "arm64", "amd64" ]
  rows = [{ os = "linux", arch = "arm64" },
          { os = "linux", arch = "amd64" },
          { os = "osx", arch = "arm64" },
          { os = "osx", arch = "amd64" },
          { os = "windows", arch = "arm64" },
          { os = "windows", arch = "amd64" }]

  # 
  [hooks.command]
    # Enable or disable all before, success, and failure hooks.
    # Supported values are [`NEVER`, `ALWAYS`, `RELEASE`, `SNAPSHOT`].
    # Defaults to `ALWAYS`.
    #  
    active = "ALWAYS"

    # Execute commands if the condition evaluates to `true`.
    #  
    condition = "'{{ Env.CI }}' == true"

    # A map of command environment variables.
    # Accepts values from `matrix`.
    #  
    environment.FOO = "bar"

    # Includes the default matrix.
    # 
    applyDefaultMatrix = false

    # Configures matrix variables.
    # Values will be inherited from `hooks`.
    # 
    matrix.vars.os = [ "linux", "osx", "windows" ]
    matrix.vars.arch= [ "arm64", "amd64" ]
    rows = [{ os = "linux", arch = "arm64" },
            { os = "linux", arch = "amd64" },
            { os = "osx", arch = "arm64" },
            { os = "osx", arch = "amd64" },
            { os = "windows", arch = "arm64" },
            { os = "windows", arch = "amd64" }]

    # The type of hook
    # Valid entries are `before`, `success`, `failure`.
    # 
    
      # Let the release continue if the hook fails.
      # Defaults to `false`.
      # 
      continueOnError = true

      # Print command out/err to log.
      # Defaults to `false`.
      # 
      verbose = true

      # Enable or disable this hook.
      # Supported values are [`NEVER`, `ALWAYS`, `RELEASE`, `SNAPSHOT`].
      # Defaults to `ALWAYS`.
      #  
      active = "ALWAYS"

      # A map of local environment variables.
      # Accepts values from `matrix`.
      #  
      environment.FOO = "bar"

      # Includes the default matrix.
      # 
      applyDefaultMatrix = false

      # Configures matrix variables.
      # Values will be inherited from `command`.
      # 
      matrix.vars.os = [ "linux", "osx", "windows" ]
      matrix.vars.arch= [ "arm64", "amd64" ]
      rows = [{ os = "linux", arch = "arm64" },
              { os = "linux", arch = "amd64" },
              { os = "osx", arch = "arm64" },
              { os = "osx", arch = "amd64" },
              { os = "windows", arch = "arm64" },
              { os = "windows", arch = "amd64" }]

      # Execute the command if the condition evaluates to `true`.
      #  
      condition = "'{{ Env.CI }}' == true"

      # The command to be invoked.
      # Accepts values from `matrix`.
      #  
      cmd = "{{basedir}}/notifier.sh {{event.name}} {{event.type}} {{projectVersion}}"

      # Filters this hook based on the given step.
      # 
      filter.includes = ["release"]
      filter.excludes = ["publish"]

      # Filters this hook based on the current platform.
      # Use a `!` prefix to exclude a platform
      # 
      platforms = ["linux", "!windows"]
{
  // 
  "hooks": {
    // Enable or disable all hooks.
    // Supported values are [`NEVER`, `ALWAYS`, `RELEASE`, `SNAPSHOT`].
    // Defaults to `ALWAYS`.
    //  
    "active": "ALWAYS",

    // Execute hooks if the condition evaluates to `true`.
    //  
    "condition": "'{{ Env.CI }}' == true",

    // A map of global environment variables.
    // Accepts values from `matrix`.
    //  
    "environment": {
      "FOO": "bar"
    },

    // Includes the default matrix.
    // 
    "applyDefaultMatrix": false,

    // Configures matrix variables.
    // 
    "matrix": {
      "vars": {
        "os": [ "linux", "osx", "windows" ],
        "arch": [ "arm64", "amd64" ]
      },
      "rows": [
        { "os": "linux", "arch": "arm64" },
        { "os": "linux", "arch": "amd64" },
        { "os": "osx", "arch": "arm64" },
        { "os": "osx", "arch": "amd64" },
        { "os": "windows", "arch": "arm64" },
        { "os": "windows", "arch": "amd64" }
      ]
    },

    // 
    "command": {
      // Enable or disable all before, success, and failure hooks.
      // Supported values are [`NEVER`, `ALWAYS`, `RELEASE`, `SNAPSHOT`].
      // Defaults to `ALWAYS`.
      //  
      "active": "ALWAYS",

      // Execute commands if the condition evaluates to `true`.
      //  
      "condition": "'{{ Env.CI }}' == true",

      // A map of command environment variables.
      // Accepts values from `matrix`.
      //  
      "environment": {
        "FOO": "bar"
      },

      // Includes the default matrix.
      // 
      "applyDefaultMatrix": false,

      // Configures matrix variables.
      // Values will be inherited from `hooks`.
      // 
      "matrix": {
        "vars": {
          "os": [ "linux", "osx", "windows" ],
          "arch": [ "arm64", "amd64" ]
        },
        "rows": [
          { "os": "linux", "arch": "arm64" },
          { "os": "linux", "arch": "amd64" },
          { "os": "osx", "arch": "arm64" },
          { "os": "osx", "arch": "amd64" },
          { "os": "windows", "arch": "arm64" },
          { "os": "windows", "arch": "amd64" }
        ]
      },

      // The type of hook
      // Valid entries are `before`, `success`, `failure`.
      // 
      "before": [
        {
          // Let the release continue if the hook fails.
          // Defaults to `false`.
          // 
          "continueOnError": true,

          // Print command out/err to log.
          // Defaults to `false`.
          // 
          "verbose": true,

          // Enable or disable this hook.
          // Supported values are [`NEVER`, `ALWAYS`, `RELEASE`, `SNAPSHOT`].
          // Defaults to `ALWAYS`.
          //  
          "active": "ALWAYS",

          // A map of local environment variables.
          // Accepts values from `matrix`.
          //  
          "environment": {
            "FOO": "bar"
          },

          // Includes the default matrix.
          // 
          "applyDefaultMatrix": false,

          // Configures matrix variables.
          // Values will be inherited from `script`.
          // 
          "matrix": {
            "vars": {
              "os": [ "linux", "osx", "windows" ],
              "arch": [ "arm64", "amd64" ]
            },
            "rows": [
              { "os": "linux", "arch": "arm64" },
              { "os": "linux", "arch": "amd64" },
              { "os": "osx", "arch": "arm64" },
              { "os": "osx", "arch": "amd64" },
              { "os": "windows", "arch": "arm64" },
              { "os": "windows", "arch": "amd64" }
            ]
          },

          // Execute the command if the condition evaluates to `true`.
          //  
          "condition": "'{{ Env.CI }}' == true",

          // The command to be invoked.
          // Accepts values from `matrix`.
          //  
          "cmd": "{{basedir}}/notifier.sh {{event.name}} {{event.type}} {{projectVersion}}",

          // Filters this hook based on the given step.
          // 
          "filter": {
            "includes": ["release"],
            "excludes": ["publish"]
          },

          // Filters this hook based on the current platform.
          // Use a `!` prefix to exclude a platform
          // 
          "platforms": [
            "linux",
            "!windows"
          ]
        }
      ]
    }
  }
}
<jreleaser>
  <!--
    
  -->
  <hooks>
    <!--
      Enable or disable all hooks.
      Supported values are [`NEVER`, `ALWAYS`, `RELEASE`, `SNAPSHOT`].
      Defaults to `ALWAYS`.
       
    -->
    <active>ALWAYS</active>

    <!--
      Execute hooks if the condition evaluates to `true`.
       
    -->
    <condition>"{{ Env.CI }}" == true</condition>

    <!--
      A map of global environment variables.
      Accepts values from `matrix`.
       
    -->
    <environment>
      <FOO>bar</FOO>
    </environment>

    <!--
      Includes the default matrix.
      
    -->
    <applyDefaultMatrix>false</applyDefaultMatrix>

    <!--
      Configures matrix variables.
      
    -->
    <matrix>
      <vars>
        <os>
          <e>linux</e>
          <e>osx</e>
          <e>windows</e>
        </os>
        <arch>
          <e>arm64</e>
          <e>amd64</e>
        </arch>
      </vars>
      <rows>
        <row>
          <os>linux</os>
          <arch>arm64</arch>
        </row>
        <row>
          <os>linux</os>
          <arch>amd64</arch>
        </row>
        <row>
          <os>osx</os>
          <arch>arm64</arch>
        </row>
        <row>
          <os>osx</os>
          <arch>amd64</arch>
        </row>
        <row>
          <os>windows</os>
          <arch>arm64</arch>
        </row>
        <row>
          <os>windows</os>
          <arch>amd64</arch>
        </row>
      </rows>
    </matrix>

    <!--
      
    -->
    <command>
      <!--
        Enable or disable all before, success, and failure hooks.
        Supported values are [`NEVER`, `ALWAYS`, `RELEASE`, `SNAPSHOT`].
        Defaults to `ALWAYS`.
         
      -->
      <active>ALWAYS</active>

      <!--
        Execute scripts if the condition evaluates to `true`.
         
      -->
      <condition>"{{ Env.CI }}" == true</condition>

      <!--
        A map of command environment variables.
        Accepts values from `matrix`.
         
      -->
      <environment>
        <FOO>bar</FOO>
      </environment>

      <!--
        Includes the default matrix.
        
      -->
      <applyDefaultMatrix>false</applyDefaultMatrix>

      <!--
        Configures matrix variables.
        Values will be inherited from `hooks`.
        
      -->
      <matrix>
        <vars>
          <os>
            <e>linux</e>
            <e>osx</e>
            <e>windows</e>
          </os>
          <arch>
            <e>arm64</e>
            <e>amd64</e>
          </arch>
        </vars>
        <rows>
          <row>
            <os>linux</os>
            <arch>arm64</arch>
          </row>
          <row>
            <os>linux</os>
            <arch>amd64</arch>
          </row>
          <row>
            <os>osx</os>
            <arch>arm64</arch>
          </row>
          <row>
            <os>osx</os>
            <arch>amd64</arch>
          </row>
          <row>
            <os>windows</os>
            <arch>arm64</arch>
          </row>
          <row>
            <os>windows</os>
            <arch>amd64</arch>
          </row>
        </rows>
      </matrix>

      <!--
        The type of hook
        Valid entries are `before`, `success`, `failure`.
        
      -->
      <before>
        <commandHook>
          <!--
            Let the release continue if the hook fails.
            Defaults to `false`.
            
          -->
          <continueOnError>true</continueOnError>

          <!--
            Print command out/err to log.
            Defaults to `false`.
            
          -->
          <verbose>true</verbose>

          <!--
            Enable or disable this hook.
            Supported values are [`NEVER`, `ALWAYS`, `RELEASE`, `SNAPSHOT`].
            Defaults to `ALWAYS`.
             
          -->
          <active>ALWAYS</active>

          <!--
            A map of local environment variables.
            Accepts values from `matrix`.
             
          -->
          <environment>
            <FOO>bar</FOO>
          </environment>

          <!--
            Includes the default matrix.
            
          -->
          <applyDefaultMatrix>false</applyDefaultMatrix>

          <!--
            Configures matrix variables.
            Values will be inherited from `script`.
            
          -->
          <matrix>
            <vars>
              <os>
                <e>linux</e>
                <e>osx</e>
                <e>windows</e>
              </os>
              <arch>
                <e>arm64</e>
                <e>amd64</e>
              </arch>
            </vars>
            <rows>
              <row>
                <os>linux</os>
                <arch>arm64</arch>
              </row>
              <row>
                <os>linux</os>
                <arch>amd64</arch>
              </row>
              <row>
                <os>osx</os>
                <arch>arm64</arch>
              </row>
              <row>
                <os>osx</os>
                <arch>amd64</arch>
              </row>
              <row>
                <os>windows</os>
                <arch>arm64</arch>
              </row>
              <row>
                <os>windows</os>
                <arch>amd64</arch>
              </row>
            </rows>
          </matrix>

          <!--
            Execute the command if the condition evaluates to `true`.
             
          -->
          <condition>"{{ Env.CI }}" == true</condition>

          <!--
            The command to be invoked.
            Accepts values from `matrix`.
             
          -->
          <cmd>{{basedir}}/notifier.sh {{event.name}} {{event.type}} {{projectVersion}}</cmd>

          <!--
            Filters this hook based on the given step.
            
          -->
          <filter>
            <includes>release</include>
            <excludes>publish</excludes>
          </filter>

          <!--
            Filters this hook based on the current platform.
            Use a `!` prefix to exclude a platform
            
          -->
          <platforms>
            <platform>linux</platform>
            <platform>!windows</platform>
          </platforms>
        </commandHook>
      </before>
    </command>
  </hooks>
</jreleaser>
jreleaser {
  // 
  hooks {
    // Enable or disable all hooks.
    // Supported values are [`NEVER`, `ALWAYS`, `RELEASE`, `SNAPSHOT`].
    // Defaults to `ALWAYS`.
    //  
    active = 'ALWAYS'

    // Execute hooks if the condition evaluates to `true`.
    //  
    condition = '"{{ Env.CI }}" == true'

    // A map of global environment variables.
    // Accepts values from `matrix`.
    //  
    environment('FOO', 'bar')

    // Includes the default matrix.
    // 
    applyDefaultMatrix = false

    // Configures matrix variables.
    // 
    matrix {
      variable('os', ['linux', 'osx', 'windows'])
      variable('arch', ['arm64', 'amd64'])

      row(os: 'linux', arch: 'arm64')
      row(os: 'linux', arch: 'amd64')
      row(os: 'osx', arch: 'arm64')
      row(os: 'osx', arch: 'amd64')
      row(os: 'windows', arch: 'arm64')
      row(os: 'windows', arch: 'amd64')
    }

    // 
    command {
      // Enable or disable all before, success, and failure hooks.
      // Supported values are [`NEVER`, `ALWAYS`, `RELEASE`, `SNAPSHOT`].
      // Defaults to `ALWAYS`.
      //  
      active: ALWAYS

      // Execute commands if the condition evaluates to `true`.
      //  
      condition = '"{{ Env.CI }}" == true'

      // A map of command environment variables.
      // Accepts values from `matrix`.
      //  
      environment('FOO', 'bar')

      // Includes the default matrix.
      // 
      applyDefaultMatrix = false

      // Configures matrix variables.
      // Values will be inherited from `hooks`.
      // 
      matrix {
        variable('os', ['linux', 'osx', 'windows'])
        variable('arch', ['arm64', 'amd64'])

        row(os: 'linux', arch: 'arm64')
        row(os: 'linux', arch: 'amd64')
        row(os: 'osx', arch: 'arm64')
        row(os: 'osx', arch: 'amd64')
        row(os: 'windows', arch: 'arm64')
        row(os: 'windows', arch: 'amd64')
      }

      // The type of hook
      // Valid entries are `before`, `success`, `failure`.
      // 
      before {
        // Let the release continue if the hook fails.
        // Defaults to `false`.
        // 
        continueOnError = true

        // Print command out/err to log.
        // Defaults to `false`.
        // 
        verbose = true

        // Enable or disable this hook.
        // Supported values are [`NEVER`, `ALWAYS`, `RELEASE`, `SNAPSHOT`].
        // Defaults to `ALWAYS`.
        //  
        active = 'ALWAYS'

        // A map of local environment variables.
        // Accepts values from `matrix`.
        //  
        environment('FOO', 'bar')

        // Includes the default matrix.
        // 
        applyDefaultMatrix = false

        // Configures matrix variables.
        // Values will be inherited from `command`.
        // 
        matrix {
          variable('os', ['linux', 'osx', 'windows'])
          variable('arch', ['arm64', 'amd64'])

          row(os: 'linux', arch: 'arm64')
          row(os: 'linux', arch: 'amd64')
          row(os: 'osx', arch: 'arm64')
          row(os: 'osx', arch: 'amd64')
          row(os: 'windows', arch: 'arm64')
          row(os: 'windows', arch: 'amd64')
        }

        // Execute the command if the condition evaluates to `true`.
        //  
        condition = '"{{ Env.CI }}" == true'

        // The command to be invoked.
        // Accepts values from `matrix`.
        //  
        cmd = "{{basedir}}/notifier.sh {{event.name}} {{event.type}} {{projectVersion}}"

        // Filters this hook based on the given step.
        // 
        filter {
          includes = ["release"]
          excludes = ["publish"]
        }

        // Filters this hook based on the current platform.
        // Use a `!` prefix to exclude a platform
        // 
        platform('linux')
        platform('!windows')
      }
    }
  }
}

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

active

jreleaser.hooks.command.active

JRELEASER_HOOKS_COMMAND_ACTIVE

Before hooks

System Property Environment Variable

active

jreleaser.hooks.command.before.${index}.active

JRELEASER_HOOKS_COMMAND_BEFORE_${index}_ACTIVE

Success hooks

System Property Environment Variable

active

jreleaser.hooks.command.success.${index}.active

JRELEASER_HOOKS_COMMAND_SUCCESS_${index}_ACTIVE

Failure hooks

System Property Environment Variable

active

jreleaser.hooks.command.failure.${index}.active

JRELEASER_HOOKS_COMMAND_FAILURE_${index}_ACTIVE

Step Names

The following step names may be used when filtering hooks:

  • session

  • download

  • assemble

  • changelog

  • catalog

  • checksum

  • sign

  • upload

  • deploy

  • release

  • prepare

  • package

  • publish

  • announce

Template Names

The following template names are also available:

{{event.type}}

One of [before, success, failure].
{{event.name}}

One of the previously mentioned steps.
{{event.stacktrace}}

Full stacktrace (if any) when type is equal to failure.

Environment Resolution

Environment variables may be defined at 3 different scopes: global, command, and local. Precedence when resolving keys goes from most specific scope to the most generic.

hooks:
  environment:
    KEY1: global1
    KEY2: global2
    KEY3: global3
  command:
    environment:
      KEY2: script1
      KEY4: script2
      KEY5: script3
    before:
      - cmd: './output.sh'
        verbose: true
        environment:
          KEY3: local1
          KEY5: local2
          KEY6: local3

Executing the command results in the following output

  [hooks] KEY1: global1
  [hooks] KEY2: script1
  [hooks] KEY3: local1
  [hooks] KEY4: script2
  [hooks] KEY5: local2
  [hooks] KEY6: local3

Conditions

You may define a condition to determine if the command should run or not. Name Templates will be evaluated before the actual condition. Expressions follow JEXL rules:

The following example shows a command hook used to run the build before the assemble step only if the running environment has an environment variable CI set to true, which is typically the case in Continuous Integration services:

hooks:
  command:
    before:
      - cmd: './mvnw -ntp verify'
        condition: '"{{ Env.CI }}" == true'
        verbose: true
        filter:
          includes: ['assemble']
Use quotes around name templates if their evaluation may result in an empty string.

Output

Command hooks have the option to provide key/value pairs as input for other steps in the current workflow. Simply use JRELEASER_OUTPUT: as prefix in the command’s output followed by key=value. For example, the following configuration adds a key named foo with a value bar before the changelog step is invoked:

hooks:
  command:
    before:
      - filter:
          includes: [changelog]
        cmd: 'echo JRELEASER_OUTPUT:foo=bar'