Script Hooks

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

Script hooks are executed before Command Hooks.

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 scripts if the condition evaluates to `true`.
  #  
  condition: '"{{ Env.CI }}" == true'

  # A map of global environment variables.
  #  
  environment:
    FOO: bar

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

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

    # A map of script environment variables..
    #  
    environment:
      FOO: bar

    # 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 script 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..
        #  
        environment:
          FOO: bar

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

        # Shell settings for executing the script.
        # Supported values are [`BASH`, `SH`, `CMD`, `PWSH`, `POWERSHELL`].
        # Defaults to `BASH`.
        # 
        shell: BASH

        # The script to be invoked.
        #  
        run: '{{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..
  #  
  environment.FOO = "bar"

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

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

    # A map of script environment variables..
    #  
    environment.FOO = "bar"

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

      # Print script 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..
      #  
      environment.FOO = "bar"

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

      # Shell settings for executing the script.
      # Supported values are [`BASH`, `SH`, `CMD`, `PWSH`, `POWERSHELL`].
      # Defaults to `BASH`.
      # 
      shell = "BASH"

      # The script to be invoked.
      #  
      run = "{{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..
    //  
    "environment": {
      "FOO": "bar"
    },

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

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

      // A map of script environment variables..
      //  
      "environment": {
        "FOO": "bar"
      },

      // 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 script 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..
          //  
          "environment": {
            "FOO": "bar"
          },

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

          // Shell settings for executing the script.
          // Supported values are [`BASH`, `SH`, `CMD`, `PWSH`, `POWERSHELL`].
          // Defaults to `BASH`.
          // 
          "shell": "BASH",

          // The script to be invoked.
          //  
          "run": "{{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.
       
    -->
    <environment>
      <FOO>bar</FOO>
    </environment>

    <!--
      
    -->
    <script>
      <!--
        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 script environment variables.
         
      -->
      <environment>
        <FOO>bar</FOO>
      </environment>

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

          <!--
            Print script 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.
             
          -->
          <environment>
            <FOO>bar</FOO>
          </environment>

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

          <!--
            Shell settings for executing the script.
            Supported values are [`BASH`, `SH`, `CMD`, `PWSH`, `POWERSHELL`].
            Defaults to `BASH`.
            
          -->
          <shell>BASH</shell>

          <!--
            The script to be invoked.
             
          -->
          <run>{{basedir}}/notifier.sh {{event.name}} {{event.type}} {{projectVersion}}</run>

          <!--
            Filters this hook based on the given step.
            
          -->
          <filter>
            <includes>release</includes>
            <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>
        </scriptHook>
      </before>
    </script>
  </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.
    //  
    environment('FOO', 'bar')

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

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

      // A map of script environment variables.
      //  
      environment('FOO', 'bar')

      // 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 script 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.
        //  
        environment('FOO', 'bar')

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

        // Shell settings for executing the script.
        // Supported values are [`BASH`, `SH`, `CMD`, `PWSH`, `POWERSHELL`].
        // Defaults to `BASH`.
        // 
        shell = 'BASH'

        // The script to be invoked.
        //  
        run = "{{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.script.active

JRELEASER_HOOKS_SCRIPT_ACTIVE

Before hooks

System Property Environment Variable

active

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

JRELEASER_HOOKS_SCRIPT_BEFORE_${index}_ACTIVE

Success hooks

System Property Environment Variable

active

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

JRELEASER_HOOKS_SCRIPT_SUCCESS_${index}_ACTIVE

Failure hooks

System Property Environment Variable

active

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

JRELEASER_HOOKS_SCRIPT_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.

Shell

The default shell is BASH. The shell command that is run internally executes a temporary file that contains the commands specified in the run property. The following shell expressions will be used depending on the set value of the shell property:

Shell Description Expression

BASH

JReleaser appends the extension .sh to the script name and substitutes for {0}

bash --noprofile --norc -eo pipefail {0}

SH

JReleaser appends the extension .sh to the script name and substitutes for {0}

sh -e {0}

CMD

The extension .cmd is appended to the script name and substitutes for {0}

%ComSpec% /D /E:ON /V:OFF /S /C "CALL "{0}""

PWSH

The PowerShell Core. JReleaser appends the extension .ps1 to the script name and substitutes for {0}

pwsh -command ". '{0}'"

POWERSHELL

The PowerShell Desktop. JReleaser appends the extension .ps1 to the script name and substitutes for {0}

powershell -command ". '{0}'"

Fail Fast

BASH sets set -eo pipefail by default while SH does not. In PWSH and POWERSHELL JReleaser prepends $ErrorActionPreference = 'stop' to script contents. It also appends if Test-Path -LiteralPath variable:\LASTEXITCODE { exit $LASTEXITCODE } to powershell scripts to reflect the script’s last exit code.

Environment Resolution

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

hooks:
  environment:
    KEY1: global1
    KEY2: global2
    KEY3: global3
  script:
    environment:
      KEY2: script1
      KEY4: script2
      KEY5: script3
    before:
      - run: |
          echo "KEY1: $KEY1"
          echo "KEY2: $KEY2"
          echo "KEY3: $KEY3"
          echo "KEY4: $KEY4"
          echo "KEY5: $KEY5"
          echo "KEY6: $KEY6"
        verbose: true
        environment:
          KEY3: local1
          KEY5: local2
          KEY6: local3

Executing the script 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 script should run or not. Name Templates will be evaluated before the actual condition. Expressions follow JEXL rules:

The following example shows a script 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:
  script:
    before:
      - run: './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

Script 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 script’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:
  script:
    before:
      - filter:
          includes: [changelog]
        run: 'echo JRELEASER_OUTPUT:foo=bar'