modrinth-publish

A GitHub Action for publishing versions on Modrinth.

Quick Start

- uses: cloudnode-pro/modrinth-publish@v2
  with:
    token: ${{ secrets.MODRINTH_TOKEN }}
    project: AABBCCDD
    version: 1.2.3
    loaders: fabric
    game-versions: 1.21.11
    files: target/Project-1.2.3.jar

Inputs

`token` (required)

A personal access token for the Modrinth API with Create versions scope. It’s strongly recommended to store this in a GitHub Repository Secret.

Personal access tokens (PATs) can be generated from the user settings.

`project` (required)

The Modrinth project ID that the version belongs to.

This can be copied from the project’s page via the ‘more options’ menu ⋮ → Copy ID.

`version` (required)

The version number, ideally following semantic versioning.

`loaders` (required)

List of supported loaders for this version.

Format each loader on a new line or use a JSON string array.

Example

loaders: fabric

loaders: |-
  paper
  spigot
  bukkit

loaders: '["paper", "spigot", "bukkit"]'

All loaders

Loader	ID
Mods
Babric	`babric`
BTA (Babric)	`bta-babric`
Fabric	`fabric`
Forge	`forge`
Java Agent	`java-agent`
Legacy Fabric	`legacy-fabric`
LiteLoader	`liteloader`
Risugami’s ModLoader	`modloader`
NeoForge	`neoforge`
NilLoader	`nilloader`
Ornithe	`ornithe`
Quilt	`quilt`
Rift	`rift`
Plugins
Bukkit	`bukkit`
BungeeCord	`bungeecord`
Folia	`folia`
Geyser	`geyser`
Paper	`paper`
Purpur	`purpur`
Spigot	`spigot`
Sponge	`sponge`
Velocity	`velocity`
Waterfall	`waterfall`
Resource Packs
Minecraft	`minecraft`
Shaders
Canvas	`canvas`
Iris	`iris`
OptiFine	`optifine`
Vanilla	`vanilla`
Data Packs
Data Pack	`datapack`

`game-versions` (required)

List of supported Minecraft versions. You can use patterns like 1.21.x and 26.1.x.

Format each version on a new line or use a JSON string array.

Example

game-versions: 1.21.x

game-versions: |-
  1.19.4
  1.20.x
  25w45a
  1.21.x
  26.1-snapshot-1

game-versions: '["1.19.4", "1.20.x", "25w45a", "1.21.x", "26.1-snapshot-1"]'

`files` (required unless draft)

One or more file paths or HTTP URLs to upload. This input is optional when the status is draft.

The allowed file extensions are .mrpack, .jar, .zip, and .litemod. For file types signature, the valid extensions are .asc, .sig, and .gpg.

Note

Supplementary files are for supporting resources like source code and documentation, not for alternative versions or variants.

Note

If you specify an HTTP URL, the action downloads the file during workflow execution and uploads it to Modrinth as a regular static file. Users downloading the version will get the file from Modrinth, not from the URL.

Format each file on a new line or use a JSON string array.

Example

files: target/YourProject-1.2.3.jar

files: |-
  target/YourProject-1.2.3.jar
  path/to/file.zip
  https://example.com/file.zip

files: '["target/YourProject-1.2.3.jar", "path/to/file.zip", "https://example.com/file.zip"]'

`primary-file`

The name (not path) of the file from files to designate as primary. If you used HTTP URLs, the name is considered the last path component, e.g. name in https://example.com/foo/name.

Example: YourProject-1.2.3.jar

`file-types`

Map of supplementary file names (not paths) to their types. If you used HTTP URLs, the name is considered the last path component, e.g. name in https://example.com/foo/name.

File types

required-resource-pack: A resource pack .zip file which is required for this version to work correctly.
optional-resource-pack: An optional resource pack .zip file which this version can use.
sources-jar: A .jar file containing source code, typically ending in -sources.jar.
javadoc-jar: A .jar file containing Javadoc documentation, typically ending in -javadoc.jar.
signature: A PGP signature for a file as either .asc, .sig, or .gpg. The name typically contains the name of the file that is signed, e.g. YourProject-1.2.3.jar.asc. Your public key should be published on a public OpenPGP key server, such as keys.openpgp.org.

Format each entry on a new line as <name>=<type> or use a JSON object.

Example

file-types: YourProject-1.2.3.jar.asc=signature

file-types:
  YourProject-1.2.3.jar.asc=signature
  resource-pack.zip=required-resource-pack

file-types: |-
  {
    "YourProject-1.2.3.jar.asc": "signature",
    "resource-pack.zip": "required-resource-pack"
  }

`name`

The name of this version.

The Modrinth UI usually names versions ‘YourProject 1.2.3’. You can use the version name to provide a very brief summary of the version/changelog.

Default: copied from version

`channel`

The release channel for this version.

Release: Final, stable version.
Beta: Feature-complete testing version.
Alpha: Early, unstable development version.

Allowed values

release, beta, alpha

Default

Inferred from the version:

If version includes alpha, will be set to alpha.
If version includes beta, rc, or pre, will be set to beta.
Otherwise, will be set to release.

`changelog`

Text describing the changes in this version. You can use Markdown formatting.

Default: empty

`dependencies`

List of dependencies for this version.

Formatted as a JSON array of objects with the following properties:

dependency_type (required): The type of the dependency. Possible values: required, optional, incompatible, embedded.
project_id: The ID of a Modrinth project. Exclusive with file_name.
version_id: The ID of the specific dependency version. If not specified, means any version of the project_id. Exclusive with file_name.
file_name: The name of a file relating to an external (non-Modrinth) dependency. Exclusive with project_id and version_id.

Dependency types

Required: The dependency is strictly required for this version to work correctly.
Optional: The dependency is used if present, but is not mandatory.
Incompatible: The dependency causes conflict and cannot coexist with this version.
Embedded: The dependency is bundled within the primary file of this version.

Example

dependencies: |-
  [{
      "project_id": "AABBCCDD",
      "dependency_type": "optional"
  }]

`status`

The status of the version.

Status descriptions

Listed (default): Public and visible to anyone.
Archived: Identical to listed but shows a message that the version is not supported.
Draft: Not public and can only be accessed by project members.
Unlisted: Not shown in the project’s versions list, but can be publicly accessed via direct URL.
Scheduled: Not public, but scheduled to be released in the future.

Allowed values: listed, archived, draft, unlisted, scheduled
Default: listed

Deprecated inputs

`api-domain` (deprecated)

The Modrinth API domain.

⚠ Warning

The Modrinth Staging API is no longer recommended for testing or as a sandbox. Instead, consider creating a ‘draft’ project on the production API and deleting it after testing. This input is scheduled for removal in v3.0.0.

Default: api.modrinth.com

`featured` (deprecated)

Whether the version is featured or not.

⚠ Warning

Modrinth has deprecated featured versions and ignores this option. This input is scheduled for removal in v3.0.0.

Allowed values: true, false
Default: true if the release channel is release, otherwise false.

`requested-status` (deprecated)

⚠ Warning

Modrinth has deprecated this option and ignores it. This input is scheduled for removal in v3.0.0.

Allowed values: listed, archived, draft, unlisted

Example Maven workflow

You can use the following example workflow to publish a version on Modrinth by creating a release on GitHub.

This example workflow will let you automatically build and upload a version on Modrinth whenever you publish a new release via GitHub. This enables you to choose the version tag and write release notes via the GitHub interface.

As the version will be taken from the release tag, in your pom.xml you can set a version like 0.0.0-SNAPSHOT and it will always be replaced with the correct version for builds via the workflow. This means you won‘t need to update the version in multiple places.

Maven workflow

name: Publish

on:
  release:
    types: [ published ]

jobs:
  publish:
    name: Publish
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v6

      - name: Set up JDK
        uses: actions/setup-java@v5
        with:
          # !!! Select the correct Java version for your project !!!
          java-version: 17
          distribution: temurin
          cache: maven

      # Takes the version tag from the release and replaces it temporarily
      # in `pom.xml` before building.
      - name: Set version from release tag
        run: mvn -B versions:set -DnewVersion=${{ github.event.release.tag_name }} -DgenerateBackupPoms=false

      - name: Build and package with Maven
        run: mvn -B clean package --file pom.xml

      - name: Upload to Modrinth
        uses: cloudnode-pro/modrinth-publish@v2
        with:
          # Configure the action as needed. The following is an example.
          token: ${{ secrets.MODRINTH_TOKEN }}
          project: ${{ vars.MODRINTH_ID }}
          name: ${{ github.event.release.name }}
          version: ${{ github.event.release.tag_name }}
          changelog: ${{ github.event.release.body }}
          loaders: |-
            paper
            spigot
            bukkit
          game-versions: |-
            1.20.x
            1.21.x
          files: target/YourProject-${{ github.event.release.tag_name }}.jar

Name		Name	Last commit message	Last commit date
Latest commit History 228 Commits
.github		.github
.idea		.idea
src		src
.gitignore		.gitignore
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
action.yaml		action.yaml
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

modrinth-publish

Quick Start

Inputs

`token` (required)

`project` (required)

`version` (required)

`loaders` (required)

`game-versions` (required)

`files` (required unless draft)

`primary-file`

`file-types`

`name`

`channel`

`changelog`

`dependencies`

`status`

`api-domain` (deprecated)

⚠ Warning

`featured` (deprecated)

⚠ Warning

`requested-status` (deprecated)

⚠ Warning

Example Maven workflow

About

Uh oh!

Releases 13

Packages

Uh oh!

Uh oh!

Contributors 3

Uh oh!

Languages

License

cloudnode-pro/modrinth-publish

Folders and files

Latest commit

History

Repository files navigation

modrinth-publish

Quick Start

Inputs

token (required)

project (required)

version (required)

loaders (required)

game-versions (required)

files (required unless draft)

primary-file

file-types

name

channel

changelog

dependencies

status

api-domain (deprecated)

⚠ Warning

featured (deprecated)

⚠ Warning

requested-status (deprecated)

⚠ Warning

Example Maven workflow

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 13

Packages 0

Uh oh!

Uh oh!

Contributors 3

Uh oh!

Languages

`token` (required)

`project` (required)

`version` (required)

`loaders` (required)

`game-versions` (required)

`files` (required unless draft)

`primary-file`

`file-types`

`name`

`channel`

`changelog`

`dependencies`

`status`

`api-domain` (deprecated)

`featured` (deprecated)

`requested-status` (deprecated)

Packages