#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
• 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

name: Release

on:
  push:
    branches: [main]
  workflow_dispatch:

permissions:
  contents: write
  pull-requests: write

jobs:
  release-pr:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Setup MoonBit
        run: |
          curl -fsSL https://cli.moonbitlang.com/install/unix.sh | bash
          echo "$HOME/.moon/bin" >> $GITHUB_PATH

      - name: Download moon-release
        run: |
          curl -fsSL -o moon-release https://github.com/dijdzv/moon-release/releases/latest/download/moon-release-linux-x86_64
          chmod +x moon-release

      - name: Configure Git
        run: |
          git config --global user.name "github-actions[bot]"
          git config --global user.email "github-actions[bot]@users.noreply.github.com"

      - name: Create Release PR
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: ./moon-release release-pr --verbose

  release:
    runs-on: ubuntu-latest
    if: github.event_name == 'push' && startsWith(github.event.head_commit.message, 'chore:') && contains(github.event.head_commit.message, 'release v')
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Setup MoonBit
        run: |
          curl -fsSL https://cli.moonbitlang.com/install/unix.sh | bash
          echo "$HOME/.moon/bin" >> $GITHUB_PATH

      - name: Download moon-release
        run: |
          curl -fsSL -o moon-release https://github.com/dijdzv/moon-release/releases/latest/download/moon-release-linux-x86_64
          chmod +x moon-release

      - name: Create Release
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: ./moon-release release --verbose

• fetch-depth: 0 - Required to analyze commit history
• release-pr job - Runs on every push: creates/updates a release PR with version bump
• release job - Runs only when a release PR is merged: creates Git tag + GitHub Release
• GITHUB_TOKEN - Automatically provided by GitHub Actions

#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. Add Credentials Step to Workflow

      - name: Configure mooncakes credentials
        env:
          MOONCAKES_TOKEN: ${{ secrets.MOONCAKES_TOKEN }}
          MOONCAKES_USERNAME: ${{ secrets.MOONCAKES_USERNAME }}
        run: |
          mkdir -p ~/.moon
          jq -n --arg token "$MOONCAKES_TOKEN" --arg username "$MOONCAKES_USERNAME" \
            '{"token": $token, "username": $username}' > ~/.moon/credentials.json

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: '20'
          registry-url: 'https://registry.npmjs.org'

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

#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,
  "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

#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/src/main/main.exe ~/.local/bin/moon-release

#Quick Start

# Initialize configuration file
moon-release init

# 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

#Differences from release-plz

#License