#moon-release

#Features

• Conventional Commits - Automatically determine semantic version from commits
• GitHub Release - Automatic creation of tags and release notes
• Release PR - Automatic creation and update of release pull requests
• mooncakes.io - Automatic publishing to the MoonBit package registry
• npm - Automatic publishing to the npm registry
• API Compatibility Check - semver-checks for breaking change detection
• Monorepo Support - Version synchronization via version_group

#Table of Contents

• GitHub Actions (CI)
  • Required Setup
  • Publishing to mooncakes.io
  • Publishing to npm
  • Configuration Summary
  • Workflow Template
• Configuration
  • Configuration Options
  • Template Variables
• Conventional Commits
• API Compatibility Check
• Monorepo Support
• CLI Usage
  • Installation
  • Quick Start
  • Commands
• Planned Features
• Differences from release-plz

#GitHub Actions

#Required Setup

#1. Repository Permissions

• Select "Read and write permissions"
• Check "Allow GitHub Actions to create and approve pull requests"

Without these settings, moon-release cannot create release PRs.

#2. Workflow File Setup

mkdir -p .github/workflows
curl -fsSL -o .github/workflows/release.yml \
  https://raw.githubusercontent.com/dijdzv/moon-release/main/templates/release.yml

• fetch-depth: 0 - Required to analyze commit history
• GITHUB_TOKEN - Automatically provided by GitHub Actions
• Supports dry-run and build-only modes via manual workflow dispatch

#Publishing to mooncakes.io (Optional)

#1. Configure GitHub Secrets

# Authenticate with mooncakes.io (creates ~/.moon/credentials.json)
moon login

#!/usr/bin/env bash
set -euo pipefail
CREDS="$HOME/.moon/credentials.json"
if [ ! -f "$CREDS" ]; then
    echo "Error: $CREDS not found. Run 'moon login' first."
    exit 1
fi
TOKEN=$(jq -r '.token' "$CREDS")
USERNAME=$(jq -r '.username' "$CREDS")
if [ -z "$TOKEN" ] || [ "$TOKEN" = "null" ]; then
    echo "Error: token not found in $CREDS"
    exit 1
fi
if [ -z "$USERNAME" ] || [ "$USERNAME" = "null" ]; then
    echo "Error: username not found in $CREDS"
    exit 1
fi
echo "Setting MOONCAKES_TOKEN..."
echo "$TOKEN" | gh secret set MOONCAKES_TOKEN
echo "Setting MOONCAKES_USERNAME..."
echo "$USERNAME" | gh secret set MOONCAKES_USERNAME
echo "Done! Mooncakes credentials registered as GitHub Secrets."

#2. Workflow Configuration

Warning: mooncakes.io does not currently provide limited-scope tokens for CI use. The token in ~/.moon/credentials.json may have full account permissions. Use at your own risk with this understanding.

#Publishing to npm (Optional)

#1. Configure Trusted Publishing on npmjs.com

1. Go to npmjs.com → your package → Settings → Configure Trusted Publishing
2. Add a new trusted publisher:
   • Repository owner: Your GitHub username or organization
   • Repository name: Your repository name
   • Workflow filename: release.yml (or your workflow file)
   • Environment: (leave empty or set if using environments)

If this is a new package, you need to publish it once manually first:

npm publish --access public

#2. Update Configuration

{
  "npm_publish": true,
  "npm_build_command": "moon build --target js"
}

#3. Update Workflow

  release:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      id-token: write  # Required for npm Trusted Publishing
    # ...
    steps:
      # ... (after Checkout, before Create Release)

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '24'

Trusted Publishing is more secure than access tokens:

• No secrets to store or rotate
• Short-lived tokens generated per-workflow
• Scoped to specific repository and workflow

#Execution Order

1. Build JS target - Runs npm_build_command (default: moon build --target js)
2. Create Git tag
3. Create GitHub Release
4. Publish to mooncakes.io (if moon_publish: true)
5. Publish to npm

#Configuration Summary

#Workflow Template

Recommended: Pin the moon-release version in your workflow to avoid unexpected breaking changes. The template uses minor version pinning (bash -s -- 0.2) which auto-updates patch releases. Check Releases for the latest version.

To always use the latest version instead, remove the version argument:

curl -fsSL https://raw.githubusercontent.com/dijdzv/moon-release/main/install.sh | bash

#Configuration

{
  "pr_title": "chore: release v{{ version }}",
  "pr_draft": false,
  "pr_labels": ["release"],
  "pr_body": "## Release v{{ version }}",
  "pr_branch_prefix": "release/",
  "base_branch": "main",
  "allow_prerelease": false,
  "git_tag_enable": true,
  "git_tag_name": "v{{ version }}",
  "git_release_enable": true,
  "git_release_draft": false,
  "git_release_name": "Release v{{ version }}",
  "git_release_body": "{{ changelog }}",
  "git_release_latest": true,
  "moon_publish": true,
  "moon_publish_frozen": false,
  "moon_publish_timeout": 300,
  "npm_publish": false,
  "npm_build_command": null,
  "npm_publish_provenance": true,
  "npm_publish_timeout": 300,
  "semver_check": false,
  "registry_check": false,
  "allow_dirty": false,
  "custom_major_increment_regex": null,
  "custom_minor_increment_regex": null,
  "max_analyze_commits": null,
  "bump_all_packages": false,
  "bootstrap_sha": null,
  "packages": []
}

#Configuration Options

#Template Variables

#Conventional Commits

#API Compatibility Check (semver_check)

{
  "semver_check": true
}

#Detected Changes

#How It Works

1. Checkout latest tag → Generate API with moon doc
2. Return to current code → Generate API with moon doc
3. Compare the two package_data.json files
4. Display warning if breaking changes are found

#Monorepo Support

{
  "packages": [
    {
      "name": "core",
      "path": "packages/core",
      "moon_publish": true,
      "npm_publish": true,
      "version_group": "main"
    },
    {
      "name": "utils",
      "path": "packages/utils",
      "moon_publish": true,
      "npm_publish": false,
      "version_group": "main"
    },
    {
      "name": "internal",
      "path": "packages/internal",
      "moon_publish": false,
      "npm_publish": false
    }
  ]
}

#Versioning Strategies

#Independent (default)

# Only changed packages are bumped
moon-release update

# Force major bump on changed packages only
moon-release update --bump major

#Fixed (bump_all_packages or --bump-all)

{
  "bump_all_packages": true
}

# Bump all packages (uses max bump type from changed packages)
moon-release update --bump-all

# Force major bump on ALL packages
moon-release update --bump major --bump-all

Note: --bump controls the bump type (major/minor/patch), while --bump-all controls the bump scope (changed-only vs all packages).

#version_group

#CLI Usage

#Installation

#From mooncakes.io (recommended)

moon install dijdzv/moon-release

#Install script

curl -fsSL https://raw.githubusercontent.com/dijdzv/moon-release/main/install.sh | bash

# Pin to minor version (recommended: auto-updates patch releases)
curl -fsSL https://raw.githubusercontent.com/dijdzv/moon-release/main/install.sh | bash -s -- 0.2

# Pin to exact version
curl -fsSL https://raw.githubusercontent.com/dijdzv/moon-release/main/install.sh | bash -s -- 0.2.8

INSTALL_DIR=/usr/local/bin curl -fsSL https://raw.githubusercontent.com/dijdzv/moon-release/main/install.sh | bash

#Download binary

# Linux (x86_64)
curl -fsSL -o moon-release https://github.com/dijdzv/moon-release/releases/latest/download/moon-release-linux-x86_64
chmod +x moon-release

# macOS (Apple Silicon)
curl -fsSL -o moon-release https://github.com/dijdzv/moon-release/releases/latest/download/moon-release-macos-arm64
chmod +x moon-release

#Build from source

git clone https://github.com/dijdzv/moon-release
cd moon-release
moon build --target native --release
cp _build/native/release/build/moon-release.exe ~/.local/bin/moon-release

#Quick Start

#Initial Setup (first time only)

# Tag the commit that represents your latest release
git tag v0.1.0
git push origin --tags

git tag v0.1.0 <commit-hash>
git push origin --tags

Recommended: Always create an initial tag. Without one, moon-release analyzes the entire commit history, which may produce unexpectedly large version bumps on repositories with a long history.

{
  "bootstrap_sha": "<commit-hash>"
}

#Regular Usage

# Check current state
moon-release check

# Preview version update
moon-release update --dry-run

# Update version
moon-release update

# Create release PR
moon-release release-pr

# Create release (tag + GitHub Release + publish)
moon-release release

#Commands

#moon-release check

moon-release check
moon-release check --verbose  # Show commit details
moon-release check -o json    # Output in JSON format

#moon-release update

moon-release update              # Auto-determine
moon-release update --bump major # Force major bump (changed packages only)
moon-release update --bump-all   # Bump all packages (monorepo)
moon-release update --bump major --bump-all  # Force major bump on all packages
moon-release update --dry-run    # Preview only
moon-release update -o json      # Output in JSON format

#moon-release release-pr

moon-release release-pr
moon-release release-pr --bump major           # Force major bump
moon-release release-pr --bump-all             # Include all packages
moon-release release-pr --bump major --bump-all # Force major on all packages
moon-release release-pr --dry-run

#moon-release release

moon-release release
moon-release release --bump major           # Force major bump
moon-release release --bump-all             # Include all packages
moon-release release --bump major --bump-all # Force major on all packages
moon-release release --prerelease alpha     # Prerelease
moon-release release --dry-run

#moon-release set-version

moon-release set-version 1.0.0

#moon-release init

moon-release init
moon-release init --force  # Overwrite

#moon-release generate-completions

moon-release generate-completions bash > ~/.local/share/bash-completion/completions/moon-release
moon-release generate-completions zsh > ~/.zfunc/_moon-release
moon-release generate-completions fish > ~/.config/fish/completions/moon-release.fish

#moon-release generate-schema

moon-release generate-schema > release-schema.json

#Planned Features

• Per-package release PRs - Create separate release PRs for each package (or version_group) in a monorepo, instead of bundling all changes into a single PR
• Per-package release - Create tags and publish each package independently when its release PR is merged
• WebAssembly registry publishing - Publish to a Wasm component registry (e.g., warg, wa.dev)

#Differences from release-plz

#License