title	Prerelease Builds
sidebar_label	Prerelease Builds
description	Automated prerelease builds from the next branch with signed and notarized macOS installers.

Prerelease Builds

MCPProxy supports automated prerelease builds from the next branch with signed and notarized macOS installers.

Branch Strategy

• main branch: Stable releases (hotfixes and production builds)
• next branch: Prerelease builds with latest features

Downloading Prerelease Builds

Option 1: GitHub Web Interface

1. Go to GitHub Actions
2. Click on the latest successful "Prerelease" workflow run
3. Scroll to Artifacts section
4. Download:
   • dmg-darwin-arm64 (Apple Silicon Macs)
   • dmg-darwin-amd64 (Intel Macs)
   • versioned-linux-amd64, versioned-windows-amd64, etc. (other platforms)

Option 2: Command Line

# List recent prerelease runs
gh run list --workflow="Prerelease" --limit 5

# Download specific artifacts from a run
gh run download <RUN_ID> --name dmg-darwin-arm64    # Apple Silicon
gh run download <RUN_ID> --name dmg-darwin-amd64    # Intel Mac
gh run download <RUN_ID> --name versioned-linux-amd64  # Linux

Prerelease Versioning

• Format: {last_git_tag}-next.{commit_hash}
• Example: v0.8.4-next.5b63e2d
• Version embedded in both mcpproxy and mcpproxy-tray binaries

Release Candidate (RC) Builds

Release candidates are opt-in, fully-built prereleases published to the GitHub pre-release channel for testers who want to validate an upcoming version before it ships to stable.

Version scheme

• Format: semver vMAJOR.MINOR.PATCH-rc.N — e.g. v0.37.0-rc.1, v0.37.0-rc.2.
• The -rc.N suffix (hyphen + dot before the number) is required. It is what keeps RC tags off the stable channels: the Homebrew, Linux-repo, docs, marketing, MCP-registry, and core build/release jobs in release.yml are gated on !contains(github.ref_name, '-').
• Do not use forms like v0.37.0.RC1 or v0.37.0RC1 — without the hyphen they read as stable tags and would bypass those guards.

What an RC publishes

A v*-rc.* tag runs only prerelease.yml, which mirrors the full stable build matrix:

Platform	Artifacts	Signing
macOS (arm64, amd64)	DMG + PKG installers, tar.gz	Apple Developer ID signed and notarized
Linux (arm64, amd64)	tar.gz, .deb, .rpm	—
Windows (arm64, amd64)	.zip, installer (.exe)	Not SignPath-signed (see note below)

The GitHub release is created with prerelease: true, so it does not become releases/latest.

Windows signing: stable releases are Authenticode-signed via a dedicated SignPath job (sign-windows) in release.yml. prerelease.yml intentionally omits that step (SignPath signing adds ~1h per arch), so RC Windows installers are unsigned and will trigger a SmartScreen prompt. If signed Windows RCs become a requirement, port the sign-windows job into prerelease.yml.

What an RC does NOT do

• Not published to Homebrew (update-homebrew guarded).
• Not published to the Linux apt/rpm repos (publish-linux-repos guarded).
• Not published to the official MCP registry (mcp-registry guarded).
• Does not deploy docs or trigger marketing automation (deploy-docs, trigger-marketing-update guarded).
• Not offered as an update on stable channels:
  • The macOS tray uses GitHub releases/latest, which excludes prereleases (native/macos/MCPProxy/MCPProxy/Services/UpdateService.swift), plus a semver downgrade guard so an -rc is never treated as "newer" than the matching stable.
  • The backend/tray update check is stable-only by default (internal/tray/tray.go → releases/latest).

The running build's version decides the channel

For a released build the running binary's own version is authoritative and cannot be overridden into offering the wrong channel:

• A stable build (e.g. v0.56.0) is never offered an RC — regardless of "update_check": { "channel": "rc" } or MCPPROXY_ALLOW_PRERELEASE_UPDATES=true. A stale rc opt-in left over from a previously-installed RC therefore can never resurrect RC offers. To test an RC, install one manually (see Installing an RC below); the updater then keeps you on the RC track.
• An RC build (e.g. v0.56.0-rc.1) automatically tracks the rc channel: it is offered the next RC, and — by pure semver comparison — its graduating stable (v0.56.0-rc.1 → v0.56.0). No opt-in needed.

The update_check.channel config field and MCPPROXY_ALLOW_PRERELEASE_UPDATES env flag now only take effect on dev / unstamped builds (local go build, go install without a release tag), where there is no release identity to honor — they let developers exercise the rc path without a released RC binary.

The Swift macOS tray takes the core's update_policy.channel (from GET /api/v1/info) as an input, then applies its own build-identity clamp on top: it narrows the channel to stable when the tray app's own bundle (CFBundleShortVersionString) is a stable release. This matters for mixed versions — a stable tray app attached to a separately-installed newer RC core reports channel=rc from that core, but the tray must never update itself to an RC, so it clamps to stable regardless. The clamp is narrowing-only (it can only pin to stable, never force rc); an RC tray app keeps the core's channel. Its Sparkle allowedChannels / feed selection then follow the clamped channel. (Spec 079 FR-013a; converging the Go tray's own self-update resolution fully onto the shared checker is FR-001a.)

Installing an RC

Download the assets directly from the pre-release on the Releases page, or with the CLI:

gh release list --repo smart-mcp-proxy/mcpproxy-go        # pre-releases are tagged "Pre-release"
gh release download v0.37.0-rc.1 --repo smart-mcp-proxy/mcpproxy-go

Security Features

• macOS DMG installers: Signed with Apple Developer ID and notarized
• Code signing: All macOS binaries are signed for Gatekeeper compatibility
• Automatic quarantine protection: New servers are quarantined by default

GitHub Workflows

• Prerelease workflow (prerelease.yml): Triggered on next branch pushes and on v*-rc.* / v*-next.* tags. Publishes a GitHub pre-release.
• Release workflow (release.yml): Triggered on v* tags, but every job is gated on !contains(github.ref_name, '-') so RC/prerelease tags are skipped — a v*-rc.* tag therefore fires only prerelease.yml, never the stable release pipeline.
• Unit Tests: Run on all branches with comprehensive test coverage
• Frontend CI: Validates web UI components and build process