JBang

Unleash the power of Java with jbang. You can publish distributions as JBang catalogs.

Each separate executable will have its own JBang script. All executables will be collected in the same catalog. Existing catalogs located at the target repository will be merged into a single catalog.

Publications of snapshots is supported, in which case executables will bear the -snapshot suffix in their alias.

Legend:

  • required

  • optional

  • may use environment variable

  • accepts Name Templates

  • YAML

  • TOML

  • JSON

  • Maven

  • Gradle

# 
packagers:
  # 
  jbang:
    # Enables or disables JBang.
    # Valid values are [`NEVER`, `ALWAYS`, `RELEASE`, `SNAPSHOT`].
    # Defaults to `NEVER`.
    # 
    active: ALWAYS

    # Let the release continue if the packager fails.
    # Defaults to `false`.
    # 
    continueOnError: true

    # Custom download URL.
    #  
    downloadUrl: https://my.server.com/{{projectName}}/{{tagName}}/{{artifactFile}}

    # Additional properties used when evaluating templates.
    #  
    extraProperties:
      # Key will be capitalized and prefixed with `jbang`, i.e, `jbangFoo`.
      foo: bar

    # Directory with file templates used to prepare the JBang distribution.
    # Defaults to `src/jreleaser/distributions/${distribution.name}/jbang`.
    # If specified, path must exist.
    # 
    templateDirectory: path/to/jbang/templates

    # List of template files to be skipped.
    # Value may be an exact match or a regex.
    # 
    skipTemplates:
      - README.md.tpl

    # Git author used to commit to the repository.
    # 
    commitAuthor:
      # Name used when authoring commits.
      # Defaults to `jreleaserbot`.
      # 
      name: jreleaserbot

      # E-mail used when authoring commits.
      # Defaults to `jreleaser@kordamp.org`.
      # 
      email: jreleaser@kordamp.org

    # Git repository to push the catalog to.
    # Defaults are shown.
    # 
    catalog:
      # Enables or disables the catalog.
      # Valid values are [`NEVER`, `ALWAYS`, `RELEASE`, `SNAPSHOT`].
      # Defaults to `RELEASE`.
      # 
      active: ALWAYS


      # The owner of the catalog.
      # Defaults to the same owner as the release repository.
      # 
      owner: duke

      # The name of the catalog.
      # Defaults to `jbang-catalog`.
      # 
      name: jbang-catalog

      # The tag associated with the catalog.
      # If left unspecified, will use `{{tagName}}`.
      #  
      tagName: '{{distributionName}} {{tagName}}'

      # The target branch to use.
      # May define a `JRELEASER_JBANG_${GIT}_BRANCH` environment variable instead.
      # Defaults to the branch pointed by HEAD.
      #  
      branch: HEAD

      # Username used for authoring commits. Must have write access to the catalog.
      # If left unspecified, the `JRELEASER_JBANG_${GIT}_USERNAME`
      # environment variable must be defined.
      # Defaults to the same username as the release repository.
      #  
      username: duke

      # Password or OAuth token with write access to the catalog.
      # If left unspecified, the `JRELEASER_JBANG_${GIT}_TOKEN`
      # environment variable must be defined.
      #  
      token: __DO_NOT_SET_HERE__

      # Message when committing to the catalog.
      # If left unspecified, `{{distributionName}} {{tagName}}` will be used.
      #  
      commitMessage: '{{distributionName}} {{tagName}}'

    # The jbang executable alias.
    # If left undefined, will use `${distribution.executable}`
    # 
    alias: cli
# 
[packagers.jbang]
  # Enables or disables JBang.
  # Valid values are [`NEVER`, `ALWAYS`, `RELEASE`, `SNAPSHOT`].
  # Defaults to `NEVER`.
  # 
  active = "ALWAYS"

  # Let the release continue if the packager fails.
  # Defaults to `false`.
  # 
  continueOnError = true

  # Custom download URL.
  #  
  downloadUrl = "https://my.server.com/{{projectName}}/{{tagName}}/{{artifactFile}}"

  # Additional properties used when evaluating templates.
  #  
  extraProperties.foo = "bar"
  # Key will be capitalized and prefixed with `jbang`, i.e, `jbangFoo`.

  # Directory with file templates used to prepare the JBang distribution.
  # Defaults to `src/jreleaser/distributions/${distribution.name}/jbang`.
  # If specified, path must exist.
  # 
  templateDirectory = "path/to/jbang/templates"

  # List of template files to be skipped.
  # Value may be an exact match or a regex.
  # 
  skipTemplates = [ "README.md.tpl" ]

  # Git author used to commit to the repository.

  # Name used when authoring commits.
  # Defaults to `jreleaserbot`.
  # 
  commitAuthor.name = "jreleaserbot"

  # E-mail used when authoring commits.
  # Defaults to `jreleaser@kordamp.org`.
  # 
  commitAuthor.email = "jreleaser@kordamp.org"

  # Git repository to push the catalog to.
  # Defaults are shown.

  # Enables or disables the catalog.
  # Valid values are [`NEVER`, `ALWAYS`, `RELEASE`, `SNAPSHOT`].
  # Defaults to `RELEASE`.
  # 
  catalog.active = "ALWAYS"


  # The owner of the catalog.
  # Defaults to the same owner as the release repository.
  # 
  catalog.owner = "duke"

  # The name of the catalog.
  # Defaults to `jbang-catalog`.
  # 
  catalog.name = "jbang-catalog"

  # The tag associated with the catalog.
  # If left unspecified, will use `{{tagName}}`.
  #  
  catalog.tagName = "{{distributionName}} {{tagName}}"

  # The target branch to use.
  # May define a `JRELEASER_JBANG_${GIT}_BRANCH` environment variable instead.
  # Defaults to the branch pointed by HEAD.
  #  
  catalog.branch = "HEAD"

  # Username used for authoring commits. Must have write access to the catalog.
  # If left unspecified, the `JRELEASER_JBANG_${GIT}_USERNAME`
  # environment variable must be defined.
  # Defaults to the same username as the release repository.
  #  
  catalog.username = "duke"

  # Password or OAuth token with write access to the catalog.
  # If left unspecified, the `JRELEASER_JBANG_${GIT}_TOKEN`
  # environment variable must be defined.
  #  
  catalog.token = "__DO_NOT_SET_HERE__"

  # Message when committing to the catalog.
  # If left unspecified, `{{distributionName}} {{tagName}}` will be used.
  #  
  catalog.commitMessage = "{{distributionName}} {{tagName}}"

  # The jbang executable alias.
  # If left undefined, will use `${distribution.executable}`
  # 
  alias = "cli"
{
  // 
  "packagers": {
    // 
    "jbang": {
      // Enables or disables JBang.
      // Valid values are [`NEVER`, `ALWAYS`, `RELEASE`, `SNAPSHOT`].
      // Defaults to `NEVER`.
      // 
      "active": "ALWAYS",

      // Let the release continue if the packager fails.
      // Defaults to `false`.
      // 
      "continueOnError": true,

      // Custom download URL.
      //  
      "downloadUrl": "https://my.server.com/{{projectName}}/{{tagName}}/{{artifactFile}}",

      // Additional properties used when evaluating templates.
      //  
      "extraProperties": {
        // Key will be capitalized and prefixed with `jbang`, i.e, `jbangFoo`.
        "foo": "bar"
      },

      // Directory with file templates used to prepare the JBang distribution.
      // Defaults to `src/jreleaser/distributions/${distribution.name}/jbang`.
      // If specified, path must exist.
      // 
      "templateDirectory": "path/to/jbang/templates",

      // List of template files to be skipped.
      // Value may be an exact match or a regex.
      // 
      "skipTemplates": [
        "README.md.tpl"
      ],

      // Git author used to commit to the repository.
      // 
      "commitAuthor": {
        // Name used when authoring commits.
        // Defaults to `jreleaserbot`.
        // 
        "name": "jreleaserbot",

        // E-mail used when authoring commits.
        // Defaults to `jreleaser@kordamp.org`.
        // 
        "email": "jreleaser@kordamp.org"
      },

      // Git repository to push the catalog to.
      // Defaults are shown.
      // 
      "catalog": {
        // Enables or disables the catalog.
        // Valid values are [`NEVER`, `ALWAYS`, `RELEASE`, `SNAPSHOT`].
        // Defaults to `RELEASE`.
        // 
        "active": "ALWAYS",


        // The owner of the catalog.
        // Defaults to the same owner as the release repository.
        // 
        "owner": "duke",

        // The name of the catalog.
        // Defaults to `jbang-catalog`.
        // 
        "name": "jbang-catalog",

        // The tag associated with the catalog.
        // If left unspecified, will use `{{tagName}}`.
        //  
        "tagName": "{{distributionName}} {{tagName}}",

        // The target branch to use.
        // May define a `JRELEASER_JBANG_${GIT}_BRANCH` environment variable instead.
        // Defaults to the branch pointed by HEAD.
        //  
        "branch": "HEAD",

        // Username used for authoring commits. Must have write access to the catalog.
        // If left unspecified, the `JRELEASER_JBANG_${GIT}_USERNAME`
        // environment variable must be defined.
        // Defaults to the same username as the release repository.
        //  
        "username": "duke",

        // Password or OAuth token with write access to the catalog.
        // If left unspecified, the `JRELEASER_JBANG_${GIT}_TOKEN`
        // environment variable must be defined.
        //  
        "token": "__DO_NOT_SET_HERE__",

        // Message when committing to the catalog.
        // If left unspecified, `{{distributionName}} {{tagName}}` will be used.
        //  
        "commitMessage": "{{distributionName}} {{tagName}}"
      },

      // The jbang executable alias.
      // If left undefined, will use `${distribution.executable}`
      // 
      "alias": "cli"
    }
  }
}
<jreleaser>
  <!--
    
  -->
  <packagers>
    <!--
      
    -->
    <jbang>
      <!--
        Enables or disables JBang.
        Valid values are [`NEVER`, `ALWAYS`, `RELEASE`, `SNAPSHOT`].
        Defaults to `NEVER`.
        
      -->
      <active>ALWAYS</active>

      <!--
        Let the release continue if the packager fails.
        Defaults to `false`.
        
      -->
      <continueOnError>true</continueOnError>

      <!--
        Custom download URL.
         
      -->
      <downloadUrl>https://my.server.com/{{projectName}}/{{tagName}}/{{artifactFile}}</downloadUrl>

      <!--
        Additional properties used when evaluating templates.
         
      -->
      <extraProperties>
        <!--
          Key will be capitalized and prefixed with `jbang`, i.e, `jbangFoo`.
        -->
        <foo>bar</foo>
      </extraProperties>

      <!--
        Directory with file templates used to prepare the JBang distribution.
        Defaults to `src/jreleaser/distributions/${distribution.name}/jbang`.
        If specified, path must exist.
        
      -->
      <templateDirectory>path/to/jbang/templates</templateDirectory>

      <!--
        List of template files to be skipped.
        Value may be an exact match or a regex.
        
      -->
      <skipTemplates>
        <skipTemplate>README.md.tpl</skipTemplate>
      </skipTemplates>

      <!--
        Git author used to commit to the repository.
        
      -->
      <commitAuthor>

        <!--
           Name used when authoring commits.
          Defaults to `jreleaserbot`.
          
        -->
        <name>jreleaserbot</name>

        <!--
          E-mail used when authoring commits.
          Defaults to `jreleaser@kordamp.org`.
          
        -->
        <email>jreleaser@kordamp.org</email>
      </commitAuthor>

      <!--
        Git repository to push the catalog to.
        Defaults are shown.
        
      -->
      <catalog>
        <!--
          Enables or disables the catalog.
          Valid values are [`NEVER`, `ALWAYS`, `RELEASE`, `SNAPSHOT`].
          Defaults to `RELEASE`.
          
        -->
        <active>ALWAYS</active>


        <!--
          The owner of the catalog.
          Defaults to the same owner as the release repository.
          
        -->
        <owner>duke</owner>

        <!--
          The name of the catalog.
          Defaults to `jbang-catalog`.
          
        -->
        <name>jbang-catalog</name>

        <!--
          The tag associated with the catalog.
          If left unspecified, will use `{{tagName}}`.
           
        -->
        <tagName>{{distributionName}} {{tagName}}</tagName>

        <!--
          The target branch to use.
          May define a `JRELEASER_JBANG_${GIT}_BRANCH`` environment variable instead.
          Defaults to the branch pointed by HEAD.
           
        -->
        <branch>HEAD</branch>

        <!--
          Username used for authoring commits. Must have write access to the catalog.
          If left unspecified, the `JRELEASER_JBANG_${GIT}_USERNAME`
          environment variable must be defined.
          Defaults to the same username as the release repository.
           
        -->
        <username>duke</username>

        <!--
          Password or OAuth token with write access to the catalog.
          If left unspecified, the `JRELEASER_JBANG_${GIT}_TOKEN`
          environment variable must be defined.
           
        -->
        <token>__DO_NOT_SET_HERE__</token>

        <!--
          Message when committing to the catalog.
          If left unspecified, `{{distributionName}} {{tagName}}` will be used.
           
        -->
        <commitMessage>{{distributionName}} {{tagName}}</commitMessage>
      </catalog>

      <!--
        The jbang executable alias.
        If left undefined, will use `${distribution.executable}`
        
      -->
      <alias>cli</alias>
    </jbang>
  </packagers>
</jreleaser>
jreleaser {
  // 
  packagers {
    // 
    jbang {
      // Enables or disables JBang.
      // Valid values are [`NEVER`, `ALWAYS`, `RELEASE`, `SNAPSHOT`].
      // Defaults to `NEVER`.
      // 
      active = 'ALWAYS'

      // Let the release continue if the packager fails.
      // Defaults to `false`.
      // 
      continueOnError = true

      // Custom download URL.
      //  
      downloadUrl = 'https://my.server.com/{{projectName}}/{{tagName}}/{{artifactFile}}'

      // Additional properties used when evaluating templates.
      // Key will be capitalized and prefixed with `jbang`, i.e, `jbangFoo`.
      //  
      extraProperties.put('foo', 'bar')

      // Directory with file templates used to prepare the JBang distribution.
      // Defaults to `src/jreleaser/distributions/${distribution.name}/jbang`.
      // If specified, path must exist.
      // 
      templateDirectory = 'path/to/jbang/templates'

      // List of template files to be skipped.
      // Value may be an exact match or a regex.
      // 
      skipTemplate('README.md.tpl')

      // Git author used to commit to the repository.
      // 
      commitAuthor {
        // Name used when authoring commits.
        // Defaults to `jreleaserbot`.
        // 
        name = 'jreleaserbot'

        // E-mail used when authoring commits.
        // Defaults to `jreleaser@kordamp.org`.
        // 
        email = 'jreleaser@kordamp.org'
      }

      // Git repository to push the catalog to.
      // Defaults are shown.
      // 
      catalog {
        // Enables or disables the catalog.
        // Valid values are [`NEVER`, `ALWAYS`, `RELEASE`, `SNAPSHOT`].
        // Defaults to `RELEASE`.
        // 
        active = 'ALWAYS'


        // The owner of the catalog.
        // Defaults to the same owner as the release repository.
        // 
        owner = 'duke'

        // The name of the catalog.
        // Defaults to `jbang-catalog`.
        // 
        name = 'jbang-catalog'

        // The tag associated with the catalog.
        // If left unspecified, will use `{{tagName}}`.
        //  
        tagName = '{{distributionName}} {{tagName}}'

        // The target branch to use.
        // May define a `JRELEASER_BRANCH` environment variable instead.
        // Defaults to the branch pointed by HEAD.
        //  
        branch = 'HEAD'

        // Username used for authoring commits. Must have write access to the catalog.
        // If left unspecified, the `JRELEASER_JBANG_${GIT}_USERNAME`
        // environment variable must be defined.
        // Defaults to the same username as the release repository.
        //  
        username = 'duke'

        // Password or OAuth token with write access to the catalog.
        // If left unspecified, the `JRELEASER_JBANG_${GIT}_TOKEN`
        // environment variable must be defined.
        //  
        token = '__DO_NOT_SET_HERE__'

        # Message when committing to the catalog.
        # If left unspecified, `{{distributionName}} {{tagName}}` will be used.
        #  
        commitMessage = '{{distributionName}} {{tagName}}'
      }

      // The jbang executable alias.
      // If left undefined, will use `${distribution.executable}`
      // 
      alias = 'cli'
    }
  }
}
You must define a value for java.mainClass in the owning distribution.
When the project’s version is snapshot, unless manually updated, the default prepared template assumes JARs may be resolved from https://jitpack.io.
Aliases must be unique!

The following property names have additional meaning

Key Description

reverseRepoHost

reversed Git host, i.e. "com.github"

reverseDomain

reversed custom domain name

Assuming the current version is 1.2.3, and a distribution named app, the above configuration will generate a app.java file in the duke/jbang-catalog repository:

jbang-catalog.json
{
  "aliases": {
    "app": {
      "script-ref": "app.java",
      "description": "Sample app"
    }
  }
}
app.java
//usr/bin/env jbang "$0" "$@" ; exit $?
//JAVA 8
//DEPS com.acme:app:1.2.3

public class app {
    public static void main(String... args) throws Exception {
        com.acme.Main.main(args);
    }
}

When the version is snapshot then the catalog and the script template change to:

jbang-catalog.json
{
  "aliases": {
    "app-snapshot": {
      "script-ref": "app_snapshot.java",
      "description": "Sample app"
    }
  }
}
app_snapshot.java
//usr/bin/env jbang "$0" "$@" ; exit $?
//JAVA 8
//REPOS jitpack
//DEPS com.github.duke:app:main-SNAPSHOT

public class app_snapshot {
    public static void main(String... args) throws Exception {
        com.acme.Main.main(args);
    }
}

Tokens

The catalog token environment variable must match with the chosen Release service that is, it must be one of:

  • JRELEASER_JBANG_GITHUB_TOKEN

  • JRELEASER_JBANG_GITLAB_TOKEN

  • JRELEASER_JBANG_GITEA_TOKEN

  • JRELEASER_JBANG_CODEBERG_TOKEN

If a matching token is not found then the releaser’s token will be used instead:

  • JRELEASER_GITHUB_TOKEN

  • JRELEASER_GITLAB_TOKEN

  • JRELEASER_GITEA_TOKEN

  • JRELEASER_CODEBERG_TOKEN

On GitHub, you can’t use the default secrets.GITHUB_TOKEN as this token only works for the repository that’s running the workflow. You must configure a Personal Access Token instead.

Templates

The default location for templates is:

src/jreleaser/distributions/<distribution-name>/jbang

The following list shows the filenames that may be used to override default templates:

  • jbang.java.tpl

  • jbang-catalog.json.tpl

Any additional files found in the template directories will be copied as is unless their filename ends with .tpl in which case Name Templates substitution will take place.

Templates may be initialized using the template command

cli template, maven jreleaser:template, gradle jreleaserTemplate, ant jreleaser-template

Skip Templates

You may skip any template files by defining a set of skip rules in the skipTemplates property. For example you may use any of these expressions to skip a template named README.md.tpl:

  • README.md.tpl: matches the full template name

  • README.md: matches the transformed template name

  • README.*: matches using a regex