Publishing Strategy -- cortex

August 9, 2026 · View on GitHub

Versioning and release workflow.

Versioning

Semantic versioning (MAJOR.MINOR.PATCH). Bump type from commit prefix:

Prefix	Bump	Example
`feat!:` / `BREAKING CHANGE`	Major	`0.3.1` -> `1.0.0`
`feat:` / `feat(scope):`	Minor	`0.3.1` -> `0.4.0`
`fix:`, `docs:`, `chore:`, etc.	Patch	`0.3.1` -> `0.3.2`

Version sync

All version-bearing files must match. Update together:

The version-bearing files are declared in release/components.toml and bumped together by cargo xtask bump-version patch|minor|major:

File	Field
`Cargo.toml`	`version = "X.Y.Z"` in `[package]` (canonical source)
`Cargo.lock`	the `cortex` package entry
`server.json`	`"version": "X.Y.Z"` plus the `cortex:vX.Y.Z` image tag
`mcpb/manifest.json`	`"version": "X.Y.Z"`
`docker-compose.prod.yml`	`${CORTEX_VERSION:-X.Y.Z}` default image tag
`CHANGELOG.md`	New entry under `## [X.Y.Z]`

Plugin manifests such as .claude-plugin/plugin.json are intentionally unversioned. cargo xtask check-version-sync (via the manifest's json_no_version row) is the guardrail that prevents top-level plugin manifest version keys from coming back.

Publish workflow

just publish [major|minor|patch]

Steps executed:

Verify on main branch with clean working tree
Pull latest from origin
cargo xtask bump-version <level> — reads the current version from Cargo.toml, computes the next, and rewrites every file in release/components.toml (including Cargo.lock and a CHANGELOG.md entry)
cargo xtask check-release-versions — confirm sync + changelog
Commit: release: vX.Y.Z
Tag: vX.Y.Z
Push to origin with tags (triggers CI/CD publish workflows)

Package registries

Registry	Method	Trigger
crates.io	`cargo publish` via GitHub Actions	`v*` tag push
GHCR	Docker image build and push	`v*` tag push
MCP Registry	`server.json` under `ai.dinglebear/cortex` namespace	manual update
MCPB (Linux)	`dist/cortex-X.Y.Z-linux.mcpb`	`just build-mcpb`
MCPB (Windows)	`dist/cortex-X.Y.Z-windows.mcpb`	`bash scripts/build-mcpb.sh --target windows`

server.json

MCP Registry metadata at repo root:

{
  "name": "ai.dinglebear/cortex",
  "title": "Cortex",
  "description": "Syslog receiver and MCP server for homelab log intelligence.",
  "version": "X.Y.Z",
  "packages": [
    {
      "registryType": "oci",
      "identifier": "ghcr.io/dinglebear-ai/cortex:vX.Y.Z"
    }
  ]
}

MCPB artifact

Run before publishing a release:

just build-mcpb
bash scripts/build-mcpb.sh --target windows
npx --yes @anthropic-ai/mcpb info dist/cortex-X.Y.Z-linux.mcpb
npx --yes @anthropic-ai/mcpb info dist/cortex-X.Y.Z-windows.mcpb

The unsigned MCPBs are target-specific bundles for local stdio clients. Signing is a separate distribution step once signing keys are available.

Windows cross-compile prerequisites

--target windows builds x86_64-pc-windows-gnu from a Linux host and requires two things that are not installed by default. scripts/build-mcpb.sh checks both and fails fast with install instructions if either is missing:

The x86_64-pc-windows-gnu rustup target: rustup target add x86_64-pc-windows-gnu
A mingw-w64 linker (x86_64-w64-mingw32-gcc) on PATH:
- Debian/Ubuntu: sudo apt install gcc-mingw-w64-x86-64
- Fedora: sudo dnf install mingw64-gcc
- Arch: sudo pacman -S mingw-w64-gcc

Verification

After publishing, verify:

# crates.io
cargo install cortex --version X.Y.Z

# Docker
docker pull ghcr.io/dinglebear-ai/cortex:vX.Y.Z

# GitHub Release
gh release view vX.Y.Z