GitHub Actions

Overview

The action-mcreleaser GitHub Action allows you to automatically publish your Minecraft artifacts to multiple platforms whenever you create a release or push a tag.

The official GitHub Action is available at HSGamer/action-mcreleaser.

Prerequisites

Before setting up the action, you need:

A GitHub repository with your Minecraft project
API tokens for target platforms (stored as GitHub Secrets)
A built artifact (JAR file) ready for publishing

Quick Start

Add this workflow to .github/workflows/release.yml:

.github/workflows/release.yml

name: Publish Release

on:
  release:
    types: [published]

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Set up JDK 17
        uses: actions/setup-java@v4
        with:
          java-version: '17'
          distribution: 'temurin'
      
      - name: Build with Maven
        run: mvn clean package
      
      - name: Publish to platforms
        uses: HSGamer/action-mcreleaser@v1
        with:
          name: ${{ github.event.repository.name }}
          version: ${{ github.event.release.tag_name }}
          description: ${{ github.event.release.body }}
          game-versions: '1.20.1,1.20.4'
        env:
          MODRINTH_TOKEN: ${{ secrets.MODRINTH_TOKEN }}
          MODRINTH_PROJECT: ${{ secrets.MODRINTH_PROJECT }}
          MODRINTH_LOADERS: 'paper,spigot'
          HANGAR_KEY: ${{ secrets.HANGAR_KEY }}
          HANGAR_PROJECT: ${{ secrets.HANGAR_PROJECT }}
          HANGAR_CHANNEL: 'Release'

Workflow Configuration

Trigger on Release

Publish when a GitHub release is created:

on:
  release:
    types: [published]

Trigger on Tag Push

Publish when a version tag is pushed:

on:
  push:
    tags:
      - 'v*.*.*'

Trigger on Manual Dispatch

Allow manual workflow runs:

on:
  workflow_dispatch:
    inputs:
      version:
        description: 'Version to publish'
        required: true
      game-versions:
        description: 'Supported game versions (comma-separated)'
        required: true
        default: '1.20.1,1.20.4'

Complete Examples

Multi-Platform Publishing

Publish to Modrinth, Hangar, CurseForge, and GitHub Releases:

.github/workflows/release.yml

name: Multi-Platform Release

on:
  release:
    types: [published]

jobs:
  publish:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      packages: write
    
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
      
      - name: Set up JDK 17
        uses: actions/setup-java@v4
        with:
          java-version: '17'
          distribution: 'temurin'
          cache: 'maven'
      
      - name: Build plugin
        run: mvn clean package -DskipTests
      
      - name: Publish to all platforms
        uses: HSGamer/action-mcreleaser@v1
        with:
          name: 'MyAwesomePlugin'
          version: ${{ github.event.release.tag_name }}
          description: |
            ${{ github.event.release.body }}
            
            ## Download
            Download from your preferred platform below.
          game-versions: '1.19.4,1.20.1,1.20.4,1.21'
          announce-missing-key: 'false'
        env:
          # Modrinth
          MODRINTH_TOKEN: ${{ secrets.MODRINTH_TOKEN }}
          MODRINTH_PROJECT: ${{ secrets.MODRINTH_PROJECT }}
          MODRINTH_LOADERS: 'paper,spigot,bukkit'
          MODRINTH_VERSION_TYPE: 'release'
          MODRINTH_FEATURED: 'true'
          
          # Hangar
          HANGAR_KEY: ${{ secrets.HANGAR_KEY }}
          HANGAR_PROJECT: 'YourUsername/YourProject'
          HANGAR_CHANNEL: 'Release'
          
          # CurseForge
          CURSEFORGE_TOKEN: ${{ secrets.CURSEFORGE_TOKEN }}
          CURSEFORGE_PROJECT: ${{ secrets.CURSEFORGE_PROJECT }}
          CURSEFORGE_RELEASE_TYPE: 'release'
          
          # GitHub
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          GITHUB_REPOSITORY: ${{ github.repository }}
          GITHUB_REF: ${{ github.ref }}
          GITHUB_DRAFT: 'false'
          GITHUB_PRERELEASE: 'false'
          
          # Polymart
          POLYMART_KEY: ${{ secrets.POLYMART_KEY }}
          POLYMART_RESOURCE: ${{ secrets.POLYMART_RESOURCE }}
          POLYMART_TAG: 'release'

Beta/Pre-release Workflow

Handle beta releases differently:

.github/workflows/beta-release.yml

name: Beta Release

on:
  push:
    tags:
      - 'v*.*.*-beta*'

jobs:
  publish-beta:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Set up JDK 17
        uses: actions/setup-java@v4
        with:
          java-version: '17'
          distribution: 'temurin'
      
      - name: Build plugin
        run: mvn clean package
      
      - name: Publish beta version
        uses: HSGamer/action-mcreleaser@v1
        with:
          name: 'MyPlugin'
          version: ${{ github.ref_name }}
          description: 'Beta release - Use at your own risk'
          game-versions: '1.20.1,1.20.4'
        env:
          MODRINTH_TOKEN: ${{ secrets.MODRINTH_TOKEN }}
          MODRINTH_PROJECT: ${{ secrets.MODRINTH_PROJECT }}
          MODRINTH_LOADERS: 'paper,spigot'
          MODRINTH_VERSION_TYPE: 'beta'
          MODRINTH_FEATURED: 'false'
          
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          GITHUB_REPOSITORY: ${{ github.repository }}
          GITHUB_REF: ${{ github.ref }}
          GITHUB_PRERELEASE: 'true'

Manual Release Workflow

Manually trigger releases with custom parameters:

.github/workflows/manual-release.yml

name: Manual Release

on:
  workflow_dispatch:
    inputs:
      version:
        description: 'Version number (e.g., 1.0.0)'
        required: true
      game-versions:
        description: 'Game versions (comma-separated)'
        required: true
        default: '1.20.1,1.20.4'
      release-type:
        description: 'Release type'
        required: true
        type: choice
        options:
          - release
          - beta
          - alpha

jobs:
  manual-publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Set up JDK 17
        uses: actions/setup-java@v4
        with:
          java-version: '17'
          distribution: 'temurin'
      
      - name: Build plugin
        run: mvn clean package
      
      - name: Publish release
        uses: HSGamer/action-mcreleaser@v1
        with:
          name: 'MyPlugin'
          version: ${{ github.event.inputs.version }}
          description: 'Manual release triggered from GitHub Actions'
          game-versions: ${{ github.event.inputs.game-versions }}
        env:
          MODRINTH_TOKEN: ${{ secrets.MODRINTH_TOKEN }}
          MODRINTH_PROJECT: ${{ secrets.MODRINTH_PROJECT }}
          MODRINTH_LOADERS: 'paper,spigot'
          MODRINTH_VERSION_TYPE: ${{ github.event.inputs.release-type }}
          
          HANGAR_KEY: ${{ secrets.HANGAR_KEY }}
          HANGAR_PROJECT: ${{ secrets.HANGAR_PROJECT }}
          HANGAR_CHANNEL: ${{ github.event.inputs.release-type == 'release' && 'Release' || 'Beta' }}

Setting Up Secrets

Navigate to repository settings

Go to your GitHub repository → Settings → Secrets and variables → Actions

Add required secrets

Click “New repository secret” and add the following:For Modrinth:

MODRINTH_TOKEN: Your Modrinth API token
MODRINTH_PROJECT: Your project ID or slug

For Hangar:

HANGAR_KEY: Your Hangar API key
HANGAR_PROJECT: Your project identifier (Username/Project)

For CurseForge:

CURSEFORGE_TOKEN: Your CurseForge API token
CURSEFORGE_PROJECT: Your project ID

For Polymart:

POLYMART_KEY: Your Polymart API key
POLYMART_RESOURCE: Your resource ID

Verify secret names

Ensure secret names match exactly what’s used in your workflow file.

GitHub Token: The GITHUB_TOKEN is automatically provided by GitHub Actions. You don’t need to create it manually. It has permissions based on your workflow settings.

Action Inputs

The action accepts the following inputs:

Input	Description	Required	Default
`name`	Name of the artifact	Yes
`version`	Version of the artifact	Yes
`description`	Description of the artifact	Yes
`game-versions`	Supported game versions (comma-separated)	No
`game-version-type`	Type of game version to filter	No
`announce-missing-key`	Announce missing environment variables	No	`false`

Environment Variables

All environment variables from the Configuration section are supported. Pass them via the env: section of your workflow.

Using with Docker

Alternatively, use the Docker image directly in your workflow:

steps:
  - name: Publish with Docker
    uses: docker://ghcr.io/hsgamer/mcreleaser:master
    env:
      NAME: 'MyPlugin'
      VERSION: ${{ github.event.release.tag_name }}
      DESCRIPTION: ${{ github.event.release.body }}
      GAME_VERSIONS: '1.20.1,1.20.4'
      MODRINTH_TOKEN: ${{ secrets.MODRINTH_TOKEN }}
      MODRINTH_PROJECT: ${{ secrets.MODRINTH_PROJECT }}
      MODRINTH_LOADERS: 'paper,spigot'

Best Practices

Use caching

Enable Maven/Gradle caching to speed up builds:

- uses: actions/setup-java@v4
  with:
    cache: 'maven'

Test before publishing

Run tests before publishing:

- run: mvn test
- uses: HSGamer/action-mcreleaser@v1

Use matrix builds

Test multiple Java versions:

strategy:
  matrix:
    java: [17, 21]

Validate secrets

Check if required secrets are set before publishing.

Troubleshooting

Action Not Found

If the action can’t be found:

# Specify a specific version
uses: HSGamer/[email protected]

Permission Errors

Ensure your workflow has proper permissions:

permissions:
  contents: write
  packages: write

Missing Artifacts

Verify your build produces the expected JAR file:

- name: List artifacts
  run: ls -la target/*.jar

Failed Platform Upload

Check individual platform configuration:

Verify secret names match environment variables
Check API token permissions
Ensure project IDs are correct

Next Steps

Configuration

Configure platform-specific settings

Platforms

Learn about supported platforms

Get Started

Installation

Configuration

Guides

Platform-Specific

Advanced

Overview

Prerequisites

Quick Start

Workflow Configuration

Trigger on Release

Trigger on Tag Push

Trigger on Manual Dispatch

Complete Examples

Multi-Platform Publishing

Beta/Pre-release Workflow

Manual Release Workflow

Setting Up Secrets

Action Inputs

Environment Variables

Using with Docker

Best Practices

Use caching

Test before publishing

Use matrix builds

Validate secrets

Troubleshooting

Action Not Found

Permission Errors

Missing Artifacts

Failed Platform Upload

Next Steps

Configuration

Platforms

Build docs developers (and LLMs) love

Get Started

Installation

Configuration

Guides

Platform-Specific

Advanced

​Overview

​Prerequisites

​Quick Start

​Workflow Configuration

​Trigger on Release

​Trigger on Tag Push

​Trigger on Manual Dispatch

​Complete Examples

​Multi-Platform Publishing

​Beta/Pre-release Workflow

​Manual Release Workflow

​Setting Up Secrets

​Action Inputs

​Environment Variables

​Using with Docker

​Best Practices

Use caching

Test before publishing

Use matrix builds

Validate secrets

​Troubleshooting

​Action Not Found

​Permission Errors

​Missing Artifacts

​Failed Platform Upload

​Next Steps

Configuration

Platforms

Build docs developers (and LLMs) love

Overview

Prerequisites

Quick Start

Workflow Configuration

Trigger on Release

Trigger on Tag Push

Trigger on Manual Dispatch

Complete Examples

Multi-Platform Publishing

Beta/Pre-release Workflow

Manual Release Workflow

Setting Up Secrets

Action Inputs

Environment Variables

Using with Docker

Best Practices

Troubleshooting

Action Not Found

Permission Errors

Missing Artifacts

Failed Platform Upload

Next Steps