minecraft-ci-release

Minecraft CI / リリーススキル

ルーティングの境界

• Use when：タスクが CI/CD パイプライン、成果物の公開、バージョン管理、またはリリース管理に関する場合。
• Do not use when：タスクがゲームプレイまたはプラグインの実装に関する場合（minecraft-modding、minecraft-plugin-dev、または minecraft-datapack）。
• Do not use when：タスクがサーバーのランタイム運用またはインフラストラクチャの調整に関する場合（minecraft-server-admin）。

---

リリースのセットアップ

各リポジトリで既に使用しているリリース先と承認ポリシーを維持してください。タグから成果物をビルドし、GitHub Release を作成しても、Modrinth や CurseForge への公開は行わない構成にできます。プロジェクトで既に使用している場合、またはユーザーから依頼された場合にのみ、公開先を追加してください。コミット済みファイルにトークンを追加しないでください。

Minecraft 26.x では Java 25 を使用し、ワークフローのラベルと例にその旨を記載してください。旧バージョンの Minecraft 1.21.x プロジェクトは Java 21 を維持し、バージョンを機械的に変更するのではなく、各プロジェクト固有のローダーと Gradle の規約を維持してください。

保護されたワークフローでは、変更されない GitHub Actions のリビジョンを使用してください。以下の参照先は 2026-09-04 に上流タグで検証済みです。アクションを意図的にアップグレードする前に、上流タグを確認して更新してください。

actions/[email protected]             3d3c42e5aac5ba805825da76410c181273ba90b1
actions/[email protected]           dd06d9cba3e5552c54d9f8ea23572deb30010f7c
gradle/actions/[email protected]  9c971963bec38e04b3d30dcc455b5382be2fdbfb
actions/[email protected]      043fb46d1a93c77aae656e7c1c64a875d1fc6a0a
softprops/[email protected]  efb35369e0ad2afab669f228072c1b0d510eae64

バージョンとタグの規約

Minecraft MOD のバージョン形式は次のとおりです：{mod_version}+{mc_version}

1.0.0+26.2  ← mod 1.0.0 for MC 26.2
1.2.3+26.2
2.0.0+26.2

Git タグにはゲームのサフィックスを付けないリリースバージョンを使用し、プロジェクトでこの規約を使用している場合は、成果物のバージョンに Minecraft のバージョンを残してください。

mod_version: 1.2.3
project/artifact version: 1.2.3+26.2
tag: v1.2.3

リリースワークフローでは、ビルド前に v1.2.3 が mod_version=1.2.3 と一致することを検証する必要があります。タグから mod_version を上書きしないでください。一致しない状態が隠れてしまいます。Gradle タスクと安全な変更履歴の抽出については、公開リファレンスを参照してください。

---

コア CI ワークフロー（NeoForge + Fabric）

これは Minecraft 26.x／Java 25 の例です。テストジョブを追加した後に表示されるチェック名は、Build / Build (fabric)、Build / Build (neoforge)、Build / Test です。最初のプルリクエストが成功したら、GitHub に表示される正確な名前をブランチ保護の設定にコピーしてください。ワークフロー名やジョブ名を変更すると、必須チェックのコンテキストも変わります。

.github/workflows/build.yml

name: Build

on:
  push:
    branches: ["main", "develop"]
  pull_request:
    branches: ["main"]

permissions:
  contents: read

jobs:
  build:
    name: Build (${{ matrix.platform }})
    runs-on: ubuntu-latest
    strategy:
      matrix:
        platform: [neoforge, fabric]
      fail-fast: false

    steps:
      - name: Checkout
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1

      - name: Set up Java 25
        uses: actions/setup-java@dd06d9cba3e5552c54d9f8ea23572deb30010f7c
        with:
          java-version: "25"
          distribution: "temurin"

      - name: Setup Gradle
        uses: gradle/actions/setup-gradle@9c971963bec38e04b3d30dcc455b5382be2fdbfb
        with:
          cache-read-only: ${{ github.event_name == 'pull_request' }}

      - name: Grant execute permission for gradlew
        run: chmod +x gradlew

      - name: Build (${{ matrix.platform }})
        run: ./gradlew :${{ matrix.platform }}:build --no-daemon

      - name: Upload artifacts
        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a
        with:
          name: mod-${{ matrix.platform }}-${{ github.sha }}
          path: ${{ matrix.platform }}/build/libs/*.jar
          if-no-files-found: error

  test:
    name: Test
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
      - name: Set up Java 25
        uses: actions/setup-java@dd06d9cba3e5552c54d9f8ea23572deb30010f7c
        with:
          distribution: temurin
          java-version: "25"
      - name: Set up Gradle
        uses: gradle/actions/setup-gradle@9c971963bec38e04b3d30dcc455b5382be2fdbfb
      - name: Run tests
        run: ./gradlew test --no-daemon

---

タグ付き GitHub Release

.github/workflows/release.yml

name: Release

on:
  push:
    tags:
      - "v*"

permissions:
  contents: write      # for creating GitHub releases

jobs:
  release:
    name: Release
    runs-on: ubuntu-latest

    steps:
      - name: Checkout tagged source
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1

      - name: Set up Java 25
        uses: actions/setup-java@dd06d9cba3e5552c54d9f8ea23572deb30010f7c
        with:
          java-version: "25"
          distribution: "temurin"

      - name: Setup Gradle
        uses: gradle/actions/setup-gradle@9c971963bec38e04b3d30dcc455b5382be2fdbfb

      - name: Grant execute permission for gradlew
        run: chmod +x gradlew

      - name: Validate tag and build
        env:
          MOD_VERSION: ${{ github.ref_name }}
        run: |
          MOD_VERSION="${MOD_VERSION#v}"
          ./gradlew verifyReleaseVersion build --no-daemon \
            -PreleaseModVersion="$MOD_VERSION"

      - name: Select release artifacts
        env:
          RELEASE_TAG: ${{ github.ref_name }}
        run: |
          mkdir -p release-artifacts
          shopt -s nullglob
          select_primary() {
            local loader="$1"; shift
            local matches=( "$@" )
            if (( ${#matches[@]} != 1 )); then
              printf 'Expected one %s primary JAR, found %s: %s\n' \
                "$loader" "${#matches[@]}" "${matches[*]:-none}" >&2
              exit 1
            fi
            cp "${matches[0]}" "release-artifacts/${loader}-${RELEASE_TAG}.jar"
          }
          select_primary fabric fabric/build/libs/*-fabric.jar
          select_primary neoforge neoforge/build/libs/*-neoforge.jar

      - name: Create GitHub Release
        uses: softprops/action-gh-release@efb35369e0ad2afab669f228072c1b0d510eae64
        with:
          files: |
            release-artifacts/fabric-${{ github.ref_name }}.jar
            release-artifacts/neoforge-${{ github.ref_name }}.jar
          fail_on_unmatched_files: true
          generate_release_notes: true
          prerelease: ${{ contains(github.ref_name, '-alpha') || contains(github.ref_name, '-beta') || contains(github.ref_name, '-rc') }}

このワークフローが作成するのは GitHub Release のみです。ローダーごとに名前が異なる、主要な Fabric JAR が 1 つ、主要な NeoForge JAR が 1 つ存在することを想定しています。プロジェクトのビルドでこれらの分類子を設定し、命名規約が異なる場合は両方のパターンをまとめて変更してください。選択ステップは一致するファイルが 0 個または複数の場合に失敗し、リリース用に異なる名前でコピーすることで、誤った上書きや不完全なリリースを防ぎます。バージョンの検証後、対象に含まれる場合に限り、プロジェクト固有の公開先を追加してください。

---

Paper プラグイン CI

.github/workflows/build.yml（プラグイン）

name: Build

on:
  push:
    branches: ["main"]
  pull_request:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
      - uses: actions/setup-java@dd06d9cba3e5552c54d9f8ea23572deb30010f7c
        with:
          java-version: "25"
          distribution: "temurin"
      - uses: gradle/actions/setup-gradle@9c971963bec38e04b3d30dcc455b5382be2fdbfb
      - run: chmod +x gradlew
      - run: ./gradlew build --no-daemon
      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a
        with:
          name: plugin-${{ github.sha }}
          path: build/libs/*.jar
          if-no-files-found: error

  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
      - uses: actions/setup-java@dd06d9cba3e5552c54d9f8ea23572deb30010f7c
        with:
          java-version: "25"
          distribution: "temurin"
      - uses: gradle/actions/setup-gradle@9c971963bec38e04b3d30dcc455b5382be2fdbfb
      - run: ./gradlew test --no-daemon

---

公開と変更履歴の詳細

プロジェクトが Modrinth または CurseForge に公開する場合に限り、公開リファレンスを参照してください。現在のプラグインバージョン、26.x の jar 選択、旧バージョンの Loom における明示的な remapJar のガイダンス、バージョン検証、想定される変更履歴の見出しがない場合に失敗するパーサーについて記載されています。

---

gradle.properties のシークレットのパターン

トークンをハードコードしないでください。環境変数から読み取ってください。

# gradle.properties (committed)
mod_id=mymod
mod_version=1.0.0
minecraft_version=26.2
modrinth_project_id=AABBCCDD
curseforge_project_id=123456

# DO NOT commit tokens
# Set these as GitHub repo secrets:
# MODRINTH_TOKEN, CURSEFORGE_TOKEN

---

MOD のセマンティックバージョニング

変更	バージョンの更新
破壊的変更を伴わない新機能	マイナー：1.1.0
バグ修正のみ	パッチ：1.0.1
API／設定の破壊的変更	メジャー：2.0.0
Minecraft のバージョン更新	MOD のバージョンは維持し、+26.2 のサフィックスを変更
プレリリース	1.0.0-beta.1、1.0.0-rc.1

---

CHANGELOG.md の規約

# Changelog

## [1.1.0] — 2025-06-01
### Added
- New `/kit` command
- PDC-based kill tracker

### Fixed
- Death message not appearing on Paper 26.2

## [1.0.0] — 2025-05-01
### Added
- Initial release

公開リファレンスでは mod_version によってこのセクションを抽出し、想定される見出しがない場合は明確なエラーを返します。

---

Dependabot の設定

.github/dependabot.yml

version: 2
updates:
  - package-ecosystem: "gradle"
    directory: "/"
    schedule:
      interval: "weekly"
    groups:
      gradle-plugins:
        patterns:
          - "com.gradleup.shadow"
          - "dev.architectury.loom"
          - "com.modrinth.minotaur"
          - "net.darkhax.curseforgegradle"

  - package-ecosystem: "github-actions"
    directory: "/"
    schedule:
      interval: "weekly"

---

ビルドキャッシュのベストプラクティス

# In all workflow jobs:
- name: Setup Gradle
  uses: gradle/actions/setup-gradle@9c971963bec38e04b3d30dcc455b5382be2fdbfb
  with:
    # Read-only cache on PRs, read-write on main
    cache-read-only: ${{ github.event_name == 'pull_request' }}

---

ブランチ保護 + 必須チェック

main に推奨される GitHub ブランチ保護設定：

• 確認済みのチェックを必須にします：Build / Build (fabric)、Build / Build (neoforge)、Build / Test
• 直線的な履歴を必須にします（squash/rebase マージ）
• 署名付きコミットを必須にします（任意ですが、リリースワークフローでは推奨されます）

---

タグとリリースのスクリプト

#!/usr/bin/env bash
# scripts/release.sh <mod-version>
set -euo pipefail

VERSION="${1:?Usage: release.sh <mod-version>}"
REMOTE="${RELEASE_REMOTE:-origin}"
BRANCH="${RELEASE_BRANCH:-main}"
EXPECTED_REMOTE_URL="${RELEASE_REMOTE_URL:?Set RELEASE_REMOTE_URL to the expected push URL}"
git diff --check
[[ -z "$(git status --porcelain=v1 --untracked-files=all)" ]] \
  || { echo "Working tree contains staged, unstaged, or untracked files." >&2; exit 1; }
[[ "$(git branch --show-current)" == "$BRANCH" ]] \
  || { echo "Release must start from branch $BRANCH." >&2; exit 1; }
mapfile -t PUSH_URLS < <(git remote get-url --push --all "$REMOTE")
[[ ${#PUSH_URLS[@]} -eq 1 && "${PUSH_URLS[0]}" == "$EXPECTED_REMOTE_URL" ]] \
  || { echo "Remote $REMOTE must have one expected push URL." >&2; exit 1; }
! git rev-parse --verify --quiet "refs/tags/v${VERSION}" >/dev/null \
  || { echo "Local tag v${VERSION} already exists." >&2; exit 1; }
set +e
git ls-remote --exit-code --tags "$EXPECTED_REMOTE_URL" "refs/tags/v${VERSION}" >/dev/null
REMOTE_TAG_STATUS=$?
set -e
case "$REMOTE_TAG_STATUS" in
  0) echo "Remote tag v${VERSION} already exists." >&2; exit 1 ;;
  2) ;;
  *) echo "Could not verify remote tag v${VERSION}." >&2; exit "$REMOTE_TAG_STATUS" ;;
esac
./gradlew verifyReleaseVersion --no-daemon -PreleaseModVersion="$VERSION"
git tag --annotate "v${VERSION}" --message "Release v${VERSION}"
git push "$REMOTE" "HEAD:refs/heads/${BRANCH}"
git push "$REMOTE" "refs/tags/v${VERSION}"

このスクリプトを実行する前にバージョン／変更履歴ファイルを更新して検証し、そのリリースコミットにタグを付けてください。対象のリリースブランチと正確なプッシュ URL に合わせて、RELEASE_BRANCH、RELEASE_REMOTE、RELEASE_REMOTE_URL を設定してください。明示的な承認がない限り、公開済みのリリースを強制プッシュしたり、タグを付け直したりしないでください。

ワークフロースニペットのバリデーター

インストール済みの minecraft-ci-release スキルディレクトリから、同梱のバリデーターを実行してください：

# Run from the installed skill directory:
./scripts/validate-workflow-snippets.sh --root .

# Strict mode treats warnings as failures:
./scripts/validate-workflow-snippets.sh --root . --strict

バリデーターは同梱されており、単独で動作します。リポジトリルートの node_modules に依存せず、コピーした .agents/、.codex/、または .claude/ の minecraft-ci-release スキルディレクトリから実行してください。

ワークフロー形式の YAML、未解決のプレースホルダー、ワークフローのシークレットに関するドキュメント、完全なコミット SHA に固定されたリモートの uses: 参照を検証します。ローカルアクション（./...）と Docker アクション（docker://...）は、意図的に SHA の要件から除外されています。このスキルの SKILL.md のみを読み取ります。プロジェクトの .github/workflows ファイルや Gradle タスクは検証しません。実際のリリース前に、プロジェクトの生成物を確認し、verifyReleaseVersion を実行して、ワークフローの正確な差分と設定済みのリリース先を確認してください。

---

参考資料

• GitHub Actions のセキュリティ強化
• GitHub のブランチ保護
• Minotaur
• CurseForgeGradle