Publishing with GitHub Actions
This guide shows you how to automatically publish your Kore-generated datapacks to various platforms using GitHub Actions and the mc-publish action.
Prerequisites
- A GitHub repository containing your Kore project
- Accounts on target platforms (Modrinth, CurseForge, etc.)
- API tokens for each platform you want to publish to
What is mc-publish?
mc-publish is a GitHub Action that simplifies publishing Minecraft projects across multiple platforms including Modrinth, CurseForge, and GitHub Releases. It automatically detects project metadata and handles the complex publication process with minimal configuration.
Setting Up GitHub Secrets
Before configuring your workflow, you'll need to add your platform tokens as GitHub secrets:
- Go to your repository's Settings → Secrets and variables → Actions
- Add the following secrets:
MODRINTH_TOKEN: Your Modrinth API tokenCURSEFORGE_TOKEN: Your CurseForge API tokenGITHUB_TOKENis automatically provided by GitHub
Note: Only add secrets for platforms you plan to publish to.
Basic Workflow Setup
Create .github/workflows/publish.yml in your repository:
./gradlew koreBuild runs your main() through the Gradle plugin and generates the pack folder in build/kore/<packName>. The zip step archives that folder, with pack.mcmeta at the root of the archive, and files uploads the zip.
Advanced Configuration
For more control over the publishing process, you can customize various aspects:
Kore-Specific Configuration
Kore generates your datapack from Kotlin code, so the workflow needs a build step that runs your main() and produces a zip, then points mc-publish's files input at it.
Kore projects come in two flavours depending on the build tool you started from. Use the matching build step.
Gradle (Kore-Template)
The default Kore-Template is a Gradle project built on the Gradle plugin, which has no run task: koreBuild runs the entry point and generates the pack folder in build/kore/<packName>. The entry point writes a folder with generate() (not generateZip()), and the workflow zips that folder, from inside it so pack.mcmeta sits at the root of the archive:
PACK_NAME is the workflow-level environment variable from the basic workflow above. It must equal packName in the kore { } block, which is also the name in dataPack("..."). Then point mc-publish at the archive:
The template's own workflow publishes to Modrinth only, with loaders: datapack.
Kotlin Toolchain (formerly Amper)
Projects configured with the Kotlin Toolchain (the module.yaml / project.yaml setup, previously called Amper) ship a kotlin wrapper script instead of gradlew. The wrapper downloads the toolchain and a JDK on first run, so you don't need a separate setup-java step. The entry point calls generateZip(), which writes the archive to the out/ directory by default, so mc-publish reads files: out/*.zip:
For a multi-module project (several datapacks in one repository), target a specific module with -m:
Gate generateZip() behind an environment variable so local runs still emit loose files while CI produces the publishable zip:
Workflow Triggers
You can configure when the publishing workflow runs:
Platform-Specific Features
Modrinth
- Supports featured projects
- Automatic dependency resolution
- Rich markdown changelog support
CurseForge
- Java version specification
- Custom display name support
GitHub Releases
- Draft and prerelease support
- Asset management
This helps mc-publish automatically detect project metadata.
Best Practices
1. Version Management
Use semantic versioning and Git tags:
2. Changelog Management
Maintain a CHANGELOG.md file following Keep a Changelog format:
3. Testing Before Publishing
Add a test job before publishing:
Troubleshooting
Common Issues
- Missing files: Ensure
PACK_NAMEequalspackName, so the zip step findsbuild/kore/<packName> - Invalid tokens: Verify your secrets are correctly set in GitHub
- Permission errors: Ensure the workflow has
contents: writepermission
Debugging
Enable debug logging by adding:
Complete Example
Here's a complete workflow for a Kore datapack project:
