Use when: the task is CI/CD pipelines, artifact publishing, versioning, or release governance.Do not use when: the task is gameplay or plugin implementation (minecraft-modding, minecraft-plugin-dev, or minecraft-datapack).Do not use when: the task is server runtime operations or infrastructure tuning (minecraft-server-admin).Keep each repository's existing release destinations and approval policy. A tag can\nbuild an artifact and create a GitHub Release without publishing to Modrinth or\nCurseForge. Add a publisher only when the project already uses it or the user asks\nfor it. Never add tokens to committed files.
\nFor the current Minecraft 26.x lane, use Java 25 and state that in workflow labels\nand examples. Legacy Minecraft 1.21.x projects stay on Java 21; retain their own\nloader and Gradle conventions instead of mechanically changing their version.
\nUse an immutable GitHub Action revision in a protected workflow. The following refs\nwere verified from the upstream tags on 2026-09-04; refresh them from the upstream\ntag before intentionally upgrading an action:
\nactions/checkout@v7.0.1 3d3c42e5aac5ba805825da76410c181273ba90b1\nactions/setup-java@v6.0.0 dd06d9cba3e5552c54d9f8ea23572deb30010f7c\ngradle/actions/setup-gradle@v6.3.0 9c971963bec38e04b3d30dcc455b5382be2fdbfb\nactions/upload-artifact@v7.0.1 043fb46d1a93c77aae656e7c1c64a875d1fc6a0a\nsoftprops/action-gh-release@v3.0.3 efb35369e0ad2afab669f228072c1b0d510eae64\nMinecraft mod versions follow: {mod_version}+{mc_version}
1.0.0+26.2 ← mod 1.0.0 for MC 26.2\n1.2.3+26.2\n2.0.0+26.2\nUse a release version without the game suffix for the Git tag, and retain the\nMinecraft version in the artifact version when the project uses that convention:
\nmod_version: 1.2.3\nproject/artifact version: 1.2.3+26.2\ntag: v1.2.3\nThe release workflow must verify that v1.2.3 matches mod_version=1.2.3 before\nbuilding. Do not override mod_version from the tag, because that hides a mismatch.\nThe Gradle task and safe changelog extraction are in\nthe publishing reference.
This is a Minecraft 26.x / Java 25 example. Its displayed check names are\nBuild / Build (fabric), Build / Build (neoforge), and Build / Test after\nthe test job below is added. After the first successful pull request, copy the\nexact names GitHub displays into branch protection; workflow or job renames\nchange the required-check context.
.github/workflows/build.ymlname: Build\n\non:\n push:\n branches: [\"main\", \"develop\"]\n pull_request:\n branches: [\"main\"]\n\npermissions:\n contents: read\n\njobs:\n build:\n name: Build (${{ matrix.platform }})\n runs-on: ubuntu-latest\n strategy:\n matrix:\n platform: [neoforge, fabric]\n fail-fast: false\n\n steps:\n - name: Checkout\n uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1\n\n - name: Set up Java 25\n uses: actions/setup-java@dd06d9cba3e5552c54d9f8ea23572deb30010f7c\n with:\n java-version: \"25\"\n distribution: \"temurin\"\n\n - name: Setup Gradle\n uses: gradle/actions/setup-gradle@9c971963bec38e04b3d30dcc455b5382be2fdbfb\n with:\n cache-read-only: ${{ github.event_name == 'pull_request' }}\n\n - name: Grant execute permission for gradlew\n run: chmod +x gradlew\n\n - name: Build (${{ matrix.platform }})\n run: ./gradlew :${{ matrix.platform }}:build --no-daemon\n\n - name: Upload artifacts\n uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a\n with:\n name: mod-${{ matrix.platform }}-${{ github.sha }}\n path: ${{ matrix.platform }}/build/libs/*.jar\n if-no-files-found: error\n\n test:\n name: Test\n runs-on: ubuntu-latest\n steps:\n - name: Checkout\n uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1\n - name: Set up Java 25\n uses: actions/setup-java@dd06d9cba3e5552c54d9f8ea23572deb30010f7c\n with:\n distribution: temurin\n java-version: \"25\"\n - name: Set up Gradle\n uses: gradle/actions/setup-gradle@9c971963bec38e04b3d30dcc455b5382be2fdbfb\n - name: Run tests\n run: ./gradlew test --no-daemon\n.github/workflows/release.ymlname: Release\n\non:\n push:\n tags:\n - \"v*\"\n\npermissions:\n contents: write # for creating GitHub releases\n\njobs:\n release:\n name: Release\n runs-on: ubuntu-latest\n\n steps:\n - name: Checkout tagged source\n uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1\n\n - name: Set up Java 25\n uses: actions/setup-java@dd06d9cba3e5552c54d9f8ea23572deb30010f7c\n with:\n java-version: \"25\"\n distribution: \"temurin\"\n\n - name: Setup Gradle\n uses: gradle/actions/setup-gradle@9c971963bec38e04b3d30dcc455b5382be2fdbfb\n\n - name: Grant execute permission for gradlew\n run: chmod +x gradlew\n\n - name: Validate tag and build\n env:\n MOD_VERSION: ${{ github.ref_name }}\n run: |\n MOD_VERSION=\"${MOD_VERSION#v}\"\n ./gradlew verifyReleaseVersion build --no-daemon \\\n -PreleaseModVersion=\"$MOD_VERSION\"\n\n - name: Select release artifacts\n env:\n RELEASE_TAG: ${{ github.ref_name }}\n run: |\n mkdir -p release-artifacts\n shopt -s nullglob\n select_primary() {\n local loader=\"$1\"; shift\n local matches=( \"$@\" )\n if (( ${#matches[@]} != 1 )); then\n printf 'Expected one %s primary JAR, found %s: %s\\n' \\\n \"$loader\" \"${#matches[@]}\" \"${matches[*]:-none}\" >&2\n exit 1\n fi\n cp \"${matches[0]}\" \"release-artifacts/${loader}-${RELEASE_TAG}.jar\"\n }\n select_primary fabric fabric/build/libs/*-fabric.jar\n select_primary neoforge neoforge/build/libs/*-neoforge.jar\n\n - name: Create GitHub Release\n uses: softprops/action-gh-release@efb35369e0ad2afab669f228072c1b0d510eae64\n with:\n files: |\n release-artifacts/fabric-${{ github.ref_name }}.jar\n release-artifacts/neoforge-${{ github.ref_name }}.jar\n fail_on_unmatched_files: true\n generate_release_notes: true\n prerelease: ${{ contains(github.ref_name, '-alpha') || contains(github.ref_name, '-beta') || contains(github.ref_name, '-rc') }}\nThis workflow creates a GitHub Release only. It expects one primary Fabric JAR and\none primary NeoForge JAR with loader-distinct names. Configure those classifiers in\nthe project build, then change both patterns together if its naming convention differs.\nThe selection step fails for zero or multiple matches and copies to distinct release\nnames, preventing accidental overwrite or a partial release. Add a project-specific\npublisher after version validation only when that destination is in scope.
\n.github/workflows/build.yml (plugin)name: Build\n\non:\n push:\n branches: [\"main\"]\n pull_request:\n\njobs:\n build:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1\n - uses: actions/setup-java@dd06d9cba3e5552c54d9f8ea23572deb30010f7c\n with:\n java-version: \"25\"\n distribution: \"temurin\"\n - uses: gradle/actions/setup-gradle@9c971963bec38e04b3d30dcc455b5382be2fdbfb\n - run: chmod +x gradlew\n - run: ./gradlew build --no-daemon\n - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a\n with:\n name: plugin-${{ github.sha }}\n path: build/libs/*.jar\n if-no-files-found: error\n\n test:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1\n - uses: actions/setup-java@dd06d9cba3e5552c54d9f8ea23572deb30010f7c\n with:\n java-version: \"25\"\n distribution: \"temurin\"\n - uses: gradle/actions/setup-gradle@9c971963bec38e04b3d30dcc455b5382be2fdbfb\n - run: ./gradlew test --no-daemon\nRead the publishing reference only when the\nproject publishes to Modrinth or CurseForge. It includes current plugin versions,\n26.x jar selection, explicit legacy Loom remapJar guidance, version verification,\nand a parser that fails when the expected changelog heading is missing.
gradle.properties Secrets PatternNever hardcode tokens. Read them from environment:
\n# gradle.properties (committed)\nmod_id=mymod\nmod_version=1.0.0\nminecraft_version=26.2\nmodrinth_project_id=AABBCCDD\ncurseforge_project_id=123456\n\n# DO NOT commit tokens\n# Set these as GitHub repo secrets:\n# MODRINTH_TOKEN, CURSEFORGE_TOKEN\n| Change | \nVersion bump | \n
|---|---|
| New features, no breaking changes | \nMinor: 1.1.0 | \n
| Bug fixes only | \nPatch: 1.0.1 | \n
| API/config breaking changes | \nMajor: 2.0.0 | \n
| Minecraft version update | \nKeep mod version, change the +26.2 suffix | \n
| Pre-release | \n1.0.0-beta.1, 1.0.0-rc.1 | \n
# Changelog\n\n## [1.1.0] — 2025-06-01\n### Added\n- New `/kit` command\n- PDC-based kill tracker\n\n### Fixed\n- Death message not appearing on Paper 26.2\n\n## [1.0.0] — 2025-05-01\n### Added\n- Initial release\nThe publishing reference extracts this section by mod_version and fails clearly\nwhen the expected heading is missing.
.github/dependabot.ymlversion: 2\nupdates:\n - package-ecosystem: \"gradle\"\n directory: \"/\"\n schedule:\n interval: \"weekly\"\n groups:\n gradle-plugins:\n patterns:\n - \"com.gradleup.shadow\"\n - \"dev.architectury.loom\"\n - \"com.modrinth.minotaur\"\n - \"net.darkhax.curseforgegradle\"\n\n - package-ecosystem: \"github-actions\"\n directory: \"/\"\n schedule:\n interval: \"weekly\"\n# In all workflow jobs:\n- name: Setup Gradle\n uses: gradle/actions/setup-gradle@9c971963bec38e04b3d30dcc455b5382be2fdbfb\n with:\n # Read-only cache on PRs, read-write on main\n cache-read-only: ${{ github.event_name == 'pull_request' }}\nRecommended GitHub branch protection for main:
Build / Build (fabric), Build / Build (neoforge), and Build / Test#!/usr/bin/env bash\n# scripts/release.sh <mod-version>\nset -euo pipefail\n\nVERSION=\"${1:?Usage: release.sh <mod-version>}\"\nREMOTE=\"${RELEASE_REMOTE:-origin}\"\nBRANCH=\"${RELEASE_BRANCH:-main}\"\nEXPECTED_REMOTE_URL=\"${RELEASE_REMOTE_URL:?Set RELEASE_REMOTE_URL to the expected push URL}\"\ngit diff --check\n[[ -z \"$(git status --porcelain=v1 --untracked-files=all)\" ]] \\\n || { echo \"Working tree contains staged, unstaged, or untracked files.\" >&2; exit 1; }\n[[ \"$(git branch --show-current)\" == \"$BRANCH\" ]] \\\n || { echo \"Release must start from branch $BRANCH.\" >&2; exit 1; }\nmapfile -t PUSH_URLS < <(git remote get-url --push --all \"$REMOTE\")\n[[ ${#PUSH_URLS[@]} -eq 1 && \"${PUSH_URLS[0]}\" == \"$EXPECTED_REMOTE_URL\" ]] \\\n || { echo \"Remote $REMOTE must have one expected push URL.\" >&2; exit 1; }\n! git rev-parse --verify --quiet \"refs/tags/v${VERSION}\" >/dev/null \\\n || { echo \"Local tag v${VERSION} already exists.\" >&2; exit 1; }\nset +e\ngit ls-remote --exit-code --tags \"$EXPECTED_REMOTE_URL\" \"refs/tags/v${VERSION}\" >/dev/null\nREMOTE_TAG_STATUS=$?\nset -e\ncase \"$REMOTE_TAG_STATUS\" in\n 0) echo \"Remote tag v${VERSION} already exists.\" >&2; exit 1 ;;\n 2) ;;\n *) echo \"Could not verify remote tag v${VERSION}.\" >&2; exit \"$REMOTE_TAG_STATUS\" ;;\nesac\n./gradlew verifyReleaseVersion --no-daemon -PreleaseModVersion=\"$VERSION\"\ngit tag --annotate \"v${VERSION}\" --message \"Release v${VERSION}\"\ngit push \"$REMOTE\" \"HEAD:refs/heads/${BRANCH}\"\ngit push \"$REMOTE\" \"refs/tags/v${VERSION}\"\nUpdate and verify version/changelog files before this script, then tag that release\ncommit. Set RELEASE_BRANCH, RELEASE_REMOTE, and RELEASE_REMOTE_URL for the\nintended release branch and exact push URL. Do not force-push or retag a published\nrelease without explicit authorization.
Run the bundled validator from an installed minecraft-ci-release skill directory:
# Run from the installed skill directory:\n./scripts/validate-workflow-snippets.sh --root .\n\n# Strict mode treats warnings as failures:\n./scripts/validate-workflow-snippets.sh --root . --strict\nThe validator is bundled and self-contained. Run it from a copied .agents/,\n.codex/, or .claude/ minecraft-ci-release skill directory without relying\non repo-root node_modules.
It validates workflow-shaped YAML, unresolved placeholders, workflow secret\ndocumentation, and remote uses: references pinned to full commit SHAs. Local\nactions (./...) and Docker actions (docker://...) are intentionally excluded from\nthe SHA requirement. It reads only this skill's SKILL.md: it does not validate a\nproject's .github/workflows files or Gradle tasks. Before a real release, inspect\nthe project's generated artifacts, run verifyReleaseVersion, and review the exact\nworkflow diff and configured release destination.