Fabric release

A release is a jar that someone else will run. It must be built by CI from a tagged commit, with a clear version and changelog, and published without any credential ever touching the repository.

Versioning

Use Semantic Versioning for the mod and put the Minecraft version in build metadata:

<major>.<minor>.<patch>+<minecraft_version>     e.g. 1.4.2+26.3

• major: breaking change for users or dependent mods (config format reset, removed feature, changed public API, world-data incompatibility).
• minor: new feature, new Minecraft version port, backwards-compatible.
• patch: bug fix only.
• Pre-releases: 1.5.0-beta.1+26.3. Mark them as beta/alpha on Modrinth as well.
• fabric.mod.json gets the version through processResources ("version": "${version}"); set it in one place, gradle.properties:

mod_version=1.4.2
minecraft_version=<...>

version = "${project.mod_version}+${project.minecraft_version}"

Changelog

Keep CHANGELOG.md in "Keep a Changelog" format (https://keepachangelog.com): an ## [Unreleased] section that every PR updates, renamed to ## [1.4.2] - YYYY-MM-DD at release time, with Added / Changed / Fixed / Removed groups written for players, not for developers. CI can extract the section for the release body.

Reproducible builds

Same commit -> byte-identical jar. Add to build.gradle:

tasks.withType(AbstractArchiveTask).configureEach {
    preserveFileTimestamps = false
    reproducibleFileOrder = true
}

Also:

• Commit the Gradle wrapper (gradlew, gradle/wrapper/*) and verify it in CI (gradle/actions/wrapper-validation or the setup-gradle action's built-in validation).
• Pin every dependency to an exact version in gradle.properties - no +, latest.release or -SNAPSHOT in a release build (the template's loom_version uses -SNAPSHOT; that is acceptable for the build plugin, but pin it if you need bit-for-bit reproducibility).
• Build releases only in CI from a tag, never from a developer machine.
• The artifact to publish is build/libs/<name>-<version>.jar from the jar task on 26.1+, or from remapJar on older versions. Never publish -sources or -dev jars as the main file.

Secrets - the non-negotiable part

• Tokens (Modrinth PAT, CurseForge API token) live only in GitHub -> Settings -> Secrets and variables -> Actions, referenced as ${{ secrets.MODRINTH_TOKEN }}, ${{ secrets.CURSEFORGE_TOKEN }}. GitHub's own token is ${{ secrets.GITHUB_TOKEN }}.
• Never put a token in gradle.properties, build.gradle, a workflow file, .env, a commit message, or a log line. If one was ever committed, revoke it immediately - deleting the commit does not un-leak it.
• Give tokens the minimum scope (Modrinth: create/write versions for the project only) and give the workflow minimal permissions:.
• Workflows triggered by pull_request from forks do not get secrets; never switch to pull_request_target to "fix" that for a publish job.
• Pin third-party actions to a full commit SHA (with the version in a comment) so a compromised tag cannot steal your token.

Publishing workflow (GitHub Actions)

Triggered by pushing a tag like v1.4.2. Look up the current major versions / commit SHAs of each action before using this; the ones below are placeholders to fill in.

# .github/workflows/release.yml
name: Release
on:
  push:
    tags: ["v*"]

permissions:
  contents: write        # create the GitHub Release

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@<sha>            # vX
      - uses: actions/setup-java@<sha>          # vX
        with:
          distribution: temurin
          java-version: "25"                    # what your MC version requires
      - uses: gradle/actions/setup-gradle@<sha> # vX (also validates the wrapper)

      - name: Check tag matches mod_version
        run: |
          v=$(grep '^mod_version=' gradle.properties | cut -d= -f2)
          test "v$v" = "${GITHUB_REF_NAME}" || { echo "Tag ${GITHUB_REF_NAME} != mod_version $v"; exit 1; }

      - run: ./gradlew build

      - name: Publish to Modrinth, CurseForge and GitHub
        uses: Kir-Antipov/mc-publish@<sha>      # vX - check its README for current inputs
        with:
          modrinth-id: <MODRINTH_PROJECT_ID>
          modrinth-token: ${{ secrets.MODRINTH_TOKEN }}
          curseforge-id: <CURSEFORGE_PROJECT_ID>
          curseforge-token: ${{ secrets.CURSEFORGE_TOKEN }}
          github-token: ${{ secrets.GITHUB_TOKEN }}
          files: |
            build/libs/!(*-@(dev|sources|javadoc)).jar
          loaders: fabric
          version-type: release
          changelog-file: CHANGELOG.md
          dependencies: |
            fabric-api(required)

Alternatives:

• Minotaur (com.modrinth.minotaur, Modrinth's official Gradle plugin) - publish from a Gradle task; read the token from System.getenv("MODRINTH_TOKEN"), never from a property file. Docs: https://github.com/modrinth/minotaur
• GitHub only: gh release create "$GITHUB_REF_NAME" build/libs/*.jar --notes-file notes.md with GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}.

Project ids (Modrinth slug/id, CurseForge numeric id) are public and may be committed; tokens may not.

Release checklist

1. All changes merged; main is green in CI.
2. mod_version bumped; CHANGELOG.md section dated; README "supported versions" updated.
3. fabric.mod.json depends ranges are correct for the target Minecraft version(s).
4. ./gradlew build locally, then runClient (and runServer for non-client-only mods) on the built jar in a clean instance with only required dependencies.
5. Commit: chore(release): 1.4.2; tag: git tag -a v1.4.2 -m "v1.4.2".
6. Push the tag only with the maintainer's approval; CI builds and publishes.
7. Verify the Modrinth / CurseForge / GitHub pages: correct file, game versions, loader, and dependencies; download and launch the published jar once.

Common mistakes

• Putting modrinth.token=... in gradle.properties (even "local" ones get committed) or echoing a secret in a workflow step.
• Publishing from a laptop instead of CI; publishing an untagged commit.
• Uploading the -dev, -sources or a non-remapped jar.
• Version in the jar (fabric.mod.json) not matching the tag or the Modrinth version number.
• Declaring every Minecraft version since 1.20 as compatible on Modrinth without testing.
• Forgetting to mark Fabric API as a required dependency on Modrinth/CurseForge.
• Changelog written as commit hashes instead of user-facing changes.
• Using pull_request_target or unpinned third-party actions in a job that has publish tokens.
• Reusing a version number for a different jar (Modrinth and players' launchers cache by version).