semantic-release-pano

semantic-release plugin to publish resources (plugins/themes) to the Pano Resource System.

Install

npm install semantic-release-pano -D

Usage

The plugin can be configured in the semantic-release configuration file:

Single Configuration (File Upload)

{
  "plugins": [
    "@semantic-release/commit-analyzer",
    "@semantic-release/release-notes-generator",
    ["semantic-release-pano", {
      "resourceId": "YOUR_RESOURCE_UUID",
      "file": "dist/my-plugin.jar",
      "panoVersion": "1.0.0",
      "panoUrl": "https://api.panomc.com"
    }]
  ]
}

GitHub Link Mode (No Upload)

Instead of uploading the file, use the GitHub Release asset URL and SHA-256 hash. This is ideal for free resources that are already published as GitHub Release assets — avoids duplicate uploads.

{
  "plugins": [
    "@semantic-release/commit-analyzer",
    "@semantic-release/release-notes-generator",
    ["@semantic-release/github", {
      "assets": [{ "path": "build/libs/*.jar" }]
    }],
    ["semantic-release-pano", {
      "resourceId": "YOUR_RESOURCE_UUID",
      "file": "build/libs/my-plugin-${version}.jar",
      "panoVersion": "1.0.0",
      "useGitHubLink": true,
      "repositoryUrl": "https://github.com/YourOrg/your-repo.git"
    }]
  ]
}

Note: When using useGitHubLink, the @semantic-release/github plugin should run before semantic-release-pano in the plugin list, so that the GitHub Release and its assets are created first.

Multiple Configurations (Deploy to multiple sites)

{
  "plugins": [
    "@semantic-release/commit-analyzer",
    "@semantic-release/release-notes-generator",
    ["@semantic-release/github", {
      "assets": [{ "path": "build/libs/*.jar" }]
    }],
    ["semantic-release-pano", {
      "file": "build/libs/my-plugin-${version}.jar",
      "panoVersion": "1.0.0",
      "useGitHubLink": true,
      "repositoryUrl": "https://github.com/YourOrg/your-repo.git",
      "configs": [
        {
          "resourceId": "RESOURCE_UUID_1",
          "panoUrl": "https://api.site1.com",
          "tokenVar": "PANO_TOKEN_SITE1"
        },
        {
          "resourceId": "RESOURCE_UUID_2",
          "panoUrl": "https://api.site2.com",
          "tokenVar": "PANO_TOKEN_SITE2"
        }
      ]
    }]
  ]
}

Branch-Scoped Deployments

Restrict a config to specific release branches with the optional branches field. Configs without branches continue to run on every release branch, so existing setups keep working unchanged.

{
  "plugins": [
    "@semantic-release/commit-analyzer",
    "@semantic-release/release-notes-generator",
    ["semantic-release-pano", {
      "file": "build/libs/my-plugin-${version}.jar",
      "panoVersion": "1.0.0",
      "configs": [
        {
          "resourceId": "RESOURCE_UUID",
          "panoUrl": "https://api-dev.panomc.com",
          "tokenVar": "PANO_TOKEN",
          "branches": ["dev"]
        },
        {
          "resourceId": "RESOURCE_UUID",
          "panoUrl": "https://api.panomc.com",
          "tokenVar": "PANO_PROD_TOKEN",
          "branches": ["main"]
        }
      ]
    }]
  ]
}

With the above, a release from dev only hits api-dev.panomc.com and a release from main only hits api.panomc.com. verifyConditions also skips the inactive configs, so a missing PANO_PROD_TOKEN won't fail a dev build.

Changelog Truncation

semantic-release-generated notes can balloon — especially on the first stable release of a branch that aggregated many prereleases — and exceed the Pano backend's changelog validation budget, resulting in a BAD_REQUEST reject. By default the plugin truncates the notes to 6500 characters (including a trailing ...) before sending. Override per-config with maxChangelogLength:

{
  "configs": [
    {
      "resourceId": "...",
      "panoUrl": "https://api.panomc.com",
      "tokenVar": "PANO_PROD_TOKEN",
      "branches": ["main"],
      "maxChangelogLength": 6500
    }
  ]
}

A log line is emitted whenever truncation actually kicks in, so it's visible in the release job's output if the cap clips real content.

Configuration

Option	Type	Default	Description
configs	Array	undefined	List of configurations for multiple deployments.
resourceId	String	Required	The UUID of the Pano resource to update.
file	String	Required	Path to the file (e.g. .jar or .zip). Supports ${version} substitution.
panoVersion	String	Required	The target Pano version this release is compatible with.
panoUrl	String	https://api.panomc.com	Base URL of the Pano API.
tokenVar	String	PANO_TOKEN	Name of the environment variable containing the API token.
useGitHubLink	Boolean	false	If true, sends the GitHub Release asset URL and SHA-256 hash instead of uploading the file.
repositoryUrl	String	—	GitHub repository URL (required when useGitHubLink is true).
branches	Array<String>	undefined	If set, the config only runs when the release branch name is in this list. Omit to run on every release branch (default).
maxChangelogLength	Number	6500	Upper bound (chars) for the changelog field sent to the Pano API. When nextRelease.notes exceeds this, the body is truncated to maxChangelogLength characters total — ... suffix included — to stay under the receiving server's validation limit.

Environment Variables

Variable	Description
PANO_TOKEN	Required (default). The API token for authentication. Can be customized with tokenVar.

How It Works

Upload Mode (default)

1. Reads the local file
2. Uploads it to the Pano API as a multipart form

GitHub Link Mode (useGitHubLink: true)

1. Reads the local file and computes its SHA-256 hash
2. Builds the GitHub Release asset download URL from repositoryUrl and the release tag
3. Sends the URL and hash to the Pano API — no file upload

This is particularly useful for free resources: the file is already on GitHub Releases, so there's no need to upload it again to the Pano server.