Versioning and releases
Ark MCP uses semantic versions (MAJOR.MINOR.PATCH) and Git tags (vX.Y.Z).
The first managed release is v0.2.0. Releases are approved through pull
requests, not published for every commit to main.
Release process
Section titled “Release process”- Merge reviewed changes to
mainusing Conventional Commit messages. - Release Please opens or updates a release PR containing the version bump
and changelog. Its Python strategy updates
pyproject.tomlandsrc/ark_mcp/__init__.py; a targeted updater changes only the root package’s version inuv.lock. The release manifest tracks the same version. - Review the changelog and compatibility implications, and wait for both CI and CodeQL on the release PR’s exact head. Do not manually merge a failing release PR.
- Merge the release PR. Release Please creates a version tag and a draft GitHub Release, then dispatches Publish Release.
- Publication resolves the tag to a commit on
main, reruns the full quality/security/package, CodeQL, and container-health CI at that commit, checks version consistency, and builds the distributions. - The publisher attaches the wheel, source distribution, and
SHA256SUMS, pushes the versioned Docker image, records its digest in the release notes, and only then publishes the GitHub Release.
The initial empty .release-please-manifest.json and release-as: 0.2.0
configuration are a one-time bootstrap. Release Please fills the manifest
with 0.2.0 in the first release PR. Remove release-as from that PR before
merging; CI requires its removal once the manifest is populated so it cannot
freeze later versions. Published tags require all four version locations to
agree; never reset the manifest to bootstrap another release.
The TOML updater represents scalar fields as tagged values. Its JSONPath
therefore filters on name.value to select the root package without touching
dependency versions.
Choosing versions
Section titled “Choosing versions”| Commit | Version change |
|---|---|
fix: ... |
Patch |
feat: ... |
Minor |
feat!: ... or a BREAKING CHANGE: footer |
Minor before 1.0; major from 1.0 onward |
docs: ..., ci: ..., chore: ... |
Normally no independent release |
Use deps: for dependency updates that need release notes. Squash PRs with
a conventional title, or preserve conventional commits when using merge
commits. Inspect the generated version rather than relying on the PR title
alone. To deliberately graduate to 1.0, follow Release Please’s Release-As
override guidance and review the compatibility contract.
Only stable numeric versions are currently publishable. Alpha/beta/RC channels and PyPI publication are not configured. Versions below 1.0 remain pre-stable even though they are ordinary GitHub Releases.
Installing a release
Section titled “Installing a release”For ordinary client setup, start with guided setup.
Published v0.3.0 includes the dependency security refresh.
The historical v0.2.0 release predates it. Follow
release selection and verify
the current release’s notes, manifest and lockfile before installing.
Download the wheel and SHA256SUMS from the
GitHub Releases page.
Check the downloaded file’s SHA-256 against the checksum entry, then install
that wheel with uv pip install in a virtual environment. Do not assume that
the ark-mcp name on PyPI belongs to this project.
Container tags:
ghcr.io/byteplus-sa/ark-mcp:v0.3.0and:0.3.0: the release verified above.:latest: the newest successfully published stable numeric version.:edge: a passingmainbuild, not a release.:sha-<full-commit-sha>: a development image for a particular main commit.
Use an image digest from the release notes for an immutable deployment pin. Containers currently target the Linux AMD64 runner platform; a native ARM64 image is not published by this workflow. Configuration, credentials, state volumes, and database backups remain operator responsibilities.
The source-checkout MCP launch (uv --project ... run --frozen python -m ark_mcp) continues to use that checkout. Publishing a release does not
upgrade or restart TRAE or other MCP clients automatically.
Repository setup
Section titled “Repository setup”Enable Settings > Actions > General > Allow GitHub Actions to create and
approve pull requests. Keep the default workflow token permissions read-only;
the release job requests the specific write permissions it needs.
The publication resolver also needs job-scoped contents: write: GitHub
requires push access to view draft releases, even though this job only reads
the draft and resolves its tag.
No PAT, extra registry password, or PyPI secret is needed. Release Please uses
GITHUB_TOKEN. Since bot-created PRs and tags do not trigger ordinary event
workflows, it explicitly dispatches CI, CodeQL, and publication. A release
PR must therefore have completed dispatched checks before merging.
The workflow does not approve or merge its own release PRs. Permissions to create PRs do not replace human release approval.
Recovery
Section titled “Recovery”If publication fails, the GitHub Release remains a draft. Fix the underlying
environment or workflow issue, then dispatch Publish Release on main
with the same existing tag:
gh workflow run publish-release.yml --ref main -f tag=v0.2.0Existing assets are downloaded and compared before reuse. Differing bytes
stop publication instead of overwriting them; investigate build provenance
before any manual recovery. The container registry and GitHub are separate
systems: a failed final API call can leave a pushed image beside a draft
release. Publication is serialized, and retrying an older draft does not
move latest backwards.
Already-published releases are not republished by this workflow. Do not move their tags or replace their assets; publish a new patch instead.
Validation
Section titled “Validation”uv run python scripts/release_checks.pyuv run pytest tests/unit/test_release_checks.py tests/unit/test_release_workflows.pyPublication additionally checks tag equality and the version/name inside both distribution metadata files. CI still enforces the frozen lockfile, offline tests and coverage, lint, typing, dependency/security checks, package installation, and container health. No paid provider calls are part of a release.
Sources
Section titled “Sources”Accessed 2026-10-20: