| name | release |
| description | Cut and publish a Neko Master release — main product (Docker, v* tags) or Go agent (agent-v* tags). Use when bumping versions, writing CHANGELOG entries, tagging, or verifying CI artifacts. |
Release Process
Two independent release lines, both driven entirely by git tags:
| Line | Tag | CI workflow | Artifact |
|---|
| Main product | vX.Y.Z | .github/workflows/docker-build.yml | Multi-arch Docker image (Docker Hub + GHCR), ~20 min |
| Agent probe | agent-vX.Y.Z | .github/workflows/agent-release.yml | Multi-arch agent binaries, ~1 min |
agent-v* does not build Docker images. The agent binary version is injected at build time from the tag via ldflags — there is no version file to bump for the agent.
Main product release
- Version: bump
version in the root package.json only (apps/* keep their own independent versions; the root field is the single source of truth).
- Changelog: add a dated section to BOTH
CHANGELOG.md (Chinese) and CHANGELOG.en.md (English), Keep-a-Changelog style (## [X.Y.Z] - YYYY-MM-DD, ### 修复/Fixed, ### 优化/Changed). Link issue/PR numbers as reference-style links at the section end. Credit external contributors by handle.
- Env docs: any new environment variable must be documented in
.env.example before release.
- Test gates (all must pass):
pnpm --filter @neko-master/collector exec tsc --noEmit
pnpm --filter @neko-master/collector test
pnpm --filter @neko-master/web exec tsc --noEmit
pnpm --filter @neko-master/web exec next build
- Ship:
git push origin main
git tag -a vX.Y.Z -m "<one-line summary>"
git push origin vX.Y.Z
gh release create vX.Y.Z --title "vX.Y.Z" --notes "<highlights + upgrade notes>"
- Verify CI:
gh run list --limit 3 → the tag-branch "Build and Push Docker Image" run must end completed/success. Multi-arch builds can exceed 20 minutes; poll rather than assume.
Agent release
See docs/agent/release.en.md for full details. Short form:
cd apps/agent && go vet ./... && go test ./... && sh -n nekoagent && sh -n install.sh
git tag agent-vX.Y.Z && git push origin agent-vX.Y.Z
Keep AgentProtocolVersion (Go, internal/config/config.go) and the collector's minimum accepted protocol version in sync when the payload changes — the collector rejects too-old agents with HTTP 426.
Conventions
- Also check
docs/release-checklist.md (pre-release validation for combined product+agent releases).
- Upgrade notes in the release body must call out any automatic startup migration so operators aren't surprised by one-time log output.
- Commit messages follow conventional-commit style (
fix(scope): ..., release: vX.Y.Z — ...).
