Jreleaser

When to use

Use when setting up JReleaser for a project, creating jreleaser.yml, or adding release workflows. This skill covers GitHub releases only — the fast path that needs nothing beyond a GitHub repo and token. For package managers (Homebrew, Snap, Scoop), Maven Central, signing, or announcements, consult the docs (see bottom).

The simplest release (no config needed)

If you just want to tag a GitHub release with some files — no cross-compilation, no packaging:

# Auto-config mode: no jreleaser.yml needed at all
jreleaser release --auto-config \
  --project-name=myapp \
  --project-version=1.0.0 \
  --file=dist/myapp.zip

Or with a minimal jreleaser.yml (just creates a tagged release with auto-generated changelog):

project:
  name: myapp
  version: 1.0.0

Then run jreleaser release. That's it.

See: https://jreleaser.org/guide/latest/examples/miscellaneous/simple-release.html and auto-config-release.html

Cross-platform releases

For building and releasing binaries across platforms, every JReleaser config follows one of two patterns:

Pattern 1: Native binary (Go, Rust, Zig, C#, Deno, Swift, C++, Nim, etc.)

All native binary repos share the exact same structure — only the build commands and matrix labels differ.

# 1. Build matrix: maps language-specific targets to JReleaser platforms
matrix:
  rows:
    - { VAR1: val, VAR2: val, platform: osx-aarch_64   }
    - { VAR1: val, VAR2: val, platform: osx-x86_64     }
    - { VAR1: val, VAR2: val, platform: linux-aarch_64  }
    - { VAR1: val, VAR2: val, platform: linux-x86_64    }
    - { VAR1: val, VAR2: val, platform: windows-x86_64  }

# 2. Hooks: run the language's build command per matrix row
hooks:
  script:
    before:
      - run: |
          # language-specific build command using {{ matrix.VAR1 }}, {{ matrix.VAR2 }}
        applyDefaultMatrix: true
        verbose: true
        filter:
          includes: ['assemble']

# 3. Project metadata
project:
  name: myapp
  description: My CLI tool
  links:
    homepage: https://github.com/OWNER/REPO
  authors:
    - Your Name
  license: MIT
  inceptionYear: 2024
  stereotype: CLI

# 4. Release config (same for everyone)
release:
  github:
    overwrite: true
    changelog:
      formatted: ALWAYS
      preset: conventional-commits
      contributors:
        format: '- {{contributorName}}{{#contributorUsernameAsLink}} ({{.}}){{/contributorUsernameAsLink}}'

# 5. Archive assembly (same structure for everyone)
assemble:
  archive:
    myapp:
      active: ALWAYS
      formats: [ ZIP ]
      applyDefaultMatrix: true
      archiveName: '{{distributionName}}-{{projectVersion}}-MATRIX_VARS'
      fileSets:
        - input: 'target/BUILD_OUTPUT_DIR'
          output: 'bin'
          includes: [ 'myapp{.exe,}' ]
        - input: '.'
          includes: [ 'LICENSE' ]

# 6. Distribution (same for everyone)
distributions:
  myapp:
    executable:
      windowsExtension: exe

To get the exact build commands and matrix for your language, each has:

• A helloworld repo with working config: github.com/jreleaser/helloworld-
• An example doc page explaining the setup (fetch as markdown for efficiency)

| Name | Doc page | Build approach | |---|---|---| | go | miscellaneous/go.html | go build per GOOS/GOARCH | | rustx | miscellaneous/rust.html | cargo-zigbuild per Rust target triple | | zig | miscellaneous/zig.html | zig build-exe per arch-os | | csharp | miscellaneous/csharp.html | dotnet publish per runtime ID | | fsharp | miscellaneous/fsharp.html | dotnet publish per runtime ID | | deno | miscellaneous/deno.html | deno compile --target per target | | bun | miscellaneous/bun.html | bun build --compile --target per target | | swift | miscellaneous/swift.html | swift build (macOS/Linux only) | | cpp | miscellaneous/cpp.html | CMake per platform | | nim | miscellaneous/nim.html | nim compile per platform | | crystal | miscellaneous/crystal.html | crystal build per platform | | odin | miscellaneous/odin.html | odin build per platform | | haskell | miscellaneous/haskell.html | stack build per platform | | elixir | miscellaneous/elixir.html | Burrito per platform | | ocaml | miscellaneous/ocaml.html | opam/dune per platform | | pascal | miscellaneous/pascal.html | Free Pascal per platform | | perl | miscellaneous/perl.html | PAR::Packer per platform | | ballerina | miscellaneous/ballerina.html | bal build with GraalVM |

Doc pages are at https://jreleaser.org/guide/latest/examples/. Use https://markdown.new/ for smaller token reads.

To fetch a repo's raw config:

curl -s https://raw.githubusercontent.com/jreleaser/helloworld-/main/jreleaser.yml

Pattern 2: Java

Java has sub-variants depending on how you distribute:

Simplest — single JAR (no assembly, users need Java installed):

project:
  name: myapp
  description: My Java app
  license: MIT
  stereotype: CLI
  languages:
    java:
      version: 17
      groupId: com.example
      artifactId: myapp
      mainClass: com.example.Main

release:
  github:
    overwrite: true
    changelog:
      formatted: ALWAYS
      preset: conventional-commits

distributions:
  myapp:
    type: SINGLE_JAR
    artifacts:
      - path: target/{{distributionName}}-{{projectVersion}}.jar

Java binary (JAR wrapped in a zip with scripts):

# Same project/release as above, plus:
assemble:
  javaArchive:
    myapp:
      active: ALWAYS
      formats: [ ZIP ]
      fileSets:
        - input: '.'
          includes: [ 'LICENSE' ]
      mainJar:
        path: target/{{distributionName}}-{{projectVersion}}.jar

For jlink, jpackage, or GraalVM native-image — these are more complex. Each has a doc page and helloworld repo:

| Variant | Doc page | Repo | |---|---|---| | jlink | examples/java/jlink.html | helloworld-java-jlink | | jpackage | examples/java/jpackage.html | helloworld-java-jpackage | | GraalVM native-image | examples/java/binary.html | helloworld-java-graalvm | | Java binary (scripts+JAR) | examples/java/java-binary.html | helloworld-java-bin | | Single JAR | examples/java/single-jar.html | helloworld-java-jar |

Fetch doc as markdown: https://markdown.new/https://jreleaser.org/guide/latest/

GitHub Actions workflow

Two workflows — use both. Fetch from any helloworld repo:

curl -s https://raw.githubusercontent.com/jreleaser/helloworld-go/main/.github/workflows/release.yml
curl -s https://raw.githubusercontent.com/jreleaser/helloworld-go/main/.github/workflows/early-access.yml

Release workflow (manual trigger)

name: Release
on:
  workflow_dispatch:
    inputs:
      version:
        description: 'Release version'
        required: true

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      # Add language setup step here (actions/setup-go, actions/setup-java, etc.)

      - name: Assemble
        uses: jreleaser/release-action@v2
        with:
          arguments: assemble
        env:
          JRELEASER_PROJECT_VERSION: ${{ github.event.inputs.version }}
          JRELEASER_GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

      - name: Release
        uses: jreleaser/release-action@v2
        with:
          arguments: release
        env:
          JRELEASER_PROJECT_VERSION: ${{ github.event.inputs.version }}
          JRELEASER_GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

      - name: JReleaser output
        if: always()
        uses: actions/upload-artifact@v4
        with:
          retention-days: 1
          name: jreleaser-release
          path: |
            out/jreleaser/trace.log
            out/jreleaser/output.properties

Early access workflow (on push to main)

name: EarlyAccess
on:
  push:
    branches: [ main ]

jobs:
  precheck:
    if: startsWith(github.event.head_commit.message, 'Releasing version') != true
    runs-on: ubuntu-latest
    outputs:
      VERSION: ${{ steps.vars.outputs.VERSION }}
    steps:
      - uses: actions/checkout@v4
      - id: vars
        run: echo "VERSION=$(cat VERSION)" >> $GITHUB_OUTPUT

  release:
    needs: [ precheck ]
    if: endsWith(${{ needs.precheck.outputs.VERSION }}, '-SNAPSHOT')
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      # Add language setup step here

      - name: Assemble
        uses: jreleaser/release-action@v2
        with:
          arguments: assemble
        env:
          JRELEASER_PROJECT_VERSION: ${{ needs.precheck.outputs.VERSION }}
          JRELEASER_GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

      - name: Release
        uses: jreleaser/release-action@v2
        with:
          arguments: release
        env:
          JRELEASER_PROJECT_VERSION: ${{ needs.precheck.outputs.VERSION }}
          JRELEASER_GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

      - name: JReleaser output
        if: always()
        uses: actions/upload-artifact@v4
        with:
          retention-days: 1
          name: jreleaser-release
          path: |
            out/jreleaser/trace.log
            out/jreleaser/output.properties

The early-access workflow needs a VERSION file in the repo root (e.g., 0.1.0-SNAPSHOT).

Key things to know

• Mustache templates: {{distributionName}}, {{projectVersion}}, {{ matrix.VAR }} — double braces, spaces optional inside
• stereotype: CLI tells JReleaser this is a command-line tool
• applyDefaultMatrix: true on hooks and assemble sections means "run this for each matrix row"
• platform in matrix rows must use JReleaser's naming: osx-x86_64, osx-aarch_64, linux-x86_64, linux-aarch_64, windows-x86_64, windows-aarch_64
• Platform replacements if downstream tools use different names:

``yaml platform: replacements: aarch_64: aarch64 ``

• Validate before releasing: jreleaser config checks config, jreleaser assemble tests assembly
• Environment variables override config: JRELEASER_PROJECT_VERSION, JRELEASER_GITHUB_TOKEN
• The GitHub Action is jreleaser/release-action@v2
• SLSA provenance: append -slsa to any helloworld repo name for the provenance variant

Going further (docs)

For advanced features requiring external service registration, fetch the relevant doc page as markdown for efficient reading:

https://markdown.new/https://jreleaser.org/guide/latest/reference/.html

Key pages:

• reference/packagers/index.html — Homebrew, Snap, Scoop, Chocolatey, Docker, Flatpak, WinGet
• reference/deploy/index.html — Maven Central, Nexus, Artifactory
• reference/signing.html — GPG/cosign signing
• reference/announce/index.html — Twitter, Mastodon, Slack, Discord, Zulip, etc.
• reference/catalog/index.html — SBOM generation (CycloneDX, SPDX, Syft)
• reference/hooks/index.html — script/command hooks
• reference/name-templates.html — all available template variables
• reference/matrix.html — build matrix reference
• continuous-integration/index.html — GitLab CI, Jenkins, Azure DevOps, etc.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: maxandersen
• Source: maxandersen/skills
• License: MIT

Install and usage instructions live in the source repository linked above.