Skip to main content

​
Overview

Hangar is PaperMC’s official plugin repository, designed specifically for Paper, Velocity, and Waterfall plugins. MCReleaser provides seamless integration with Hangar’s API, allowing you to publish plugin versions with full metadata including platform dependencies, game versions, and plugin dependencies. The platform automatically normalizes Minecraft versions and handles authentication through Hangar’s API key system.

​
Required Credentials

To publish to Hangar, you need:
  1. Hangar API Key: An API key from your Hangar account settings
  2. Project Slug: Your project’s identifier (found in your project URL)
Create a Hangar API key at hangar.papermc.io/auth/settings/api-keys. Make sure it has the create_version permission.

​
Configuration Options

​
HANGAR_KEY
string
required
The Hangar API key for authentication.
-e HANGAR_KEY="your_api_key_here"
​
HANGAR_PROJECT
string
required
The project slug or identifier. You can find this in your project’s URL: https://hangar.papermc.io/[owner]/[project]Use the full path: owner/projectExample: HSGamer/BetterEconomy
​
HANGAR_CHANNEL
string
required
The release channel for this version. Hangar uses channels to organize different types of releases.Common channels: Release, Beta, AlphaYou must create the channel in Hangar before using it.
-e HANGAR_CHANNEL="Release"
​
HANGAR_PLATFORM
string
required
The platform that your plugin targets.Valid platforms: PAPER, WATERFALL, VELOCITY
-e HANGAR_PLATFORM="PAPER"
The platform name is case-insensitive in the configuration, but must be one of the valid Hangar platforms.
​
HANGAR_GAME_VERSIONS
string
required
Space-separated list of Minecraft versions that your plugin supports.MCReleaser will automatically normalize and validate versions.Examples:
# Specific versions
-e HANGAR_GAME_VERSIONS="1.20.1 1.20.2 1.20.4"

# Version range
-e HANGAR_GAME_VERSIONS="1.19-1.20.4"
If not set, falls back to the common GAME_VERSIONS variable.
​
HANGAR_DEPENDENCIES
string
JSON array of plugin dependencies. Each dependency specifies a Hangar project and whether it’s required.The JSON structure should match Hangar’s PluginDependency format:
[
  {
    "name": "ProjectName",
    "required": true,
    "externalUrl": "https://optional-external-url.com",
    "namespace": "owner/project"
  }
]
Example:
-e HANGAR_DEPENDENCIES='[
  {"name": "Vault", "required": true, "namespace": "ericgrandt/vault"},
  {"name": "PlaceholderAPI", "required": false, "namespace": "hsgamer/placeholderapi"}
]'

​
Implementation Details

The Hangar platform implementation performs the following steps:
  1. Authentication: Exchanges the API key for a session token
  2. Version Normalization: Fetches and normalizes Minecraft versions
  3. Metadata Preparation: Constructs the version upload payload including:
    • Version number and description
    • Platform and game version dependencies
    • Plugin dependencies
    • Release channel
  4. Upload: Uploads the primary file with metadata to Hangar
Hangar only supports uploading a single file per version. MCReleaser will use the primary file from your bundle.

​
Complete Example

java \
  -Dname="BetterEconomy" \
  -Dversion="3.0.0" \
  -Ddescription="# BetterEconomy 3.0.0\n\nMajor update with new features" \
  -DhangarKey="your_api_key_here" \
  -DhangarProject="HSGamer/BetterEconomy" \
  -DhangarChannel="Release" \
  -DhangarPlatform="PAPER" \
  -DhangarGameVersions="1.20.1 1.20.2 1.20.4" \
  -jar mcreleaser.jar

​
Advanced: With Dependencies

Here’s an example with plugin dependencies:
Docker
docker run \
  -v $(pwd)/build/libs:/app/artifacts \
  -e NAME="EconomyBridge" \
  -e VERSION="1.5.0" \
  -e DESCRIPTION="Bridge plugin for multiple economy systems" \
  -e HANGAR_KEY="$HANGAR_API_KEY" \
  -e HANGAR_PROJECT="MyUser/EconomyBridge" \
  -e HANGAR_CHANNEL="Release" \
  -e HANGAR_PLATFORM="PAPER" \
  -e HANGAR_GAME_VERSIONS="1.20-1.20.4" \
  -e HANGAR_DEPENDENCIES='[
    {
      "name": "Vault",
      "required": true,
      "namespace": "ericgrandt/vault"
    },
    {
      "name": "BetterEconomy",
      "required": false,
      "namespace": "HSGamer/BetterEconomy"
    }
  ]' \
  ghcr.io/hsgamer/mcreleaser:master

​
Supported Platforms

Hangar supports three platform types:
  • PAPER: For Paper/Spigot/Bukkit plugins
  • VELOCITY: For Velocity proxy plugins
  • WATERFALL: For Waterfall/BungeeCord plugins
Each version upload must specify exactly one platform and the game versions it supports for that platform.

​
Source Code Reference

The Hangar platform implementation can be found in:
  • Platform logic: hangar/src/main/java/me/hsgamer/mcreleaser/hangar/HangarPlatform.java
  • Configuration keys: hangar/src/main/java/me/hsgamer/mcreleaser/hangar/HangarPropertyKey.java
  • Data models: hangar/src/main/java/me/hsgamer/mcreleaser/hangar/model/VersionUpload.java

​
Key Implementation Features

// API authentication
HttpPost tokenRequest = new HttpPost(baseUrl + "/authenticate?apiKey=" + key);
ApiSession apiSession = client.execute(tokenRequest, ...);

// Version normalization
MinecraftVersionFetcher.normalizeVersions(gameVersions, VersionTypeFilter.RELEASE)

// Upload structure
VersionUpload versionUpload = new VersionUpload(
    versionValue,
    Map.of(hangarPlatform, pluginDependencies),
    platformDependencies,
    finalDescription,
    files,
    channel
);

// Multipart upload
MultipartEntityBuilder builder = MultipartEntityBuilder.create()
    .addTextBody("versionUpload", gson.toJson(versionUpload), ContentType.APPLICATION_JSON)
    .addBinaryBody("files", fileBundle.primaryFile());

Build docs developers (and LLMs) love

Get started for freeTalk to us