Repository navigation
Releasing
The v1.0.0 wheel, sdist and npm launcher are published and match the original tag-run artifacts.
GHCR serves 1.0.0, 1.0, 1 and latest for linux/amd64 and linux/arm64, all with the tested
root digest sha256:4ff12fdcdc79e7c5cd065a3ffb685dcbe6daee518442b7751e0479e0da1e3167.
The protected recovery independently verified these package bytes and image tags before its read-only
MCP lookup failed because of a command-line parser bug. The MCP Registry entry remains incomplete
until the corrected protected recovery succeeds. The npm trusted publisher configuration has not yet
completed a real OIDC publish, so package availability does not prove that configuration works.
When a tag run fails partway through, do not retry the failed run. A retry reuses the old tag's YAML
and can attempt duplicate uploads. Instead, use the main-only release-recovery workflow dispatch.
- Create a GitHub environment named
release-recoverywith deployment restricted tomainand required reviewer approval. This is separate from the normalreleaseenvironment. - Set
TAPEBASIS_NPM_BOOTSTRAPPED=1as a release-recovery environment variable, not a secret, if the npm package was manually bootstrapped before the first tag. Thereleaseenvironment's variable is not automatically available to this separate environment. Keep it unset before the bootstrap has actually completed.
- Identify the failed source run ID and the immutable tag (e.g.,
v1.0.0). - Dispatch
release.ymlonmainwithrecover_source_runandrecover_taginputs. - Recovery skips ordinary main validation and artifact rebuilding. Instead, it requires the original tag run's validation and build jobs to have passed and its protected publish job to have started. It validates that source run's tag, commit, source metadata and artifact digest, then downloads the exact tested artifacts. GitHub Contents API base64 line wrapping and normal ZIP files without Unix file-type bits are accepted, but checksums, safe paths and expected members remain mandatory. It verifies PyPI, npm, and GHCR content match those artifacts without uploading anything.
- Only if all package registries match does it proceed to publish missing MCP Registry metadata.
The read-only registry checker accepts
--outputafter every subcommand, so it can write the status GitHub Actions consumes before deciding whether publication is needed. If any package is missing or differs, or this status lookup fails, the job stops and cannot modify packages or images. - After completion, verify each registry independently: PyPI files, npm integrity, GHCR tags, and MCP Registry metadata.
-
test.ymlruns on main and pull requests, with no publishing credentials. It tests the checkout, builds and installs the real wheel and sdist, performs an MCP initialize and tools-list exchange, tests the npm launcher, packs npm, and checks release metadata. -
release.ymlalso validates main, but its publish job runs only on a pushedv*tag. A tag that disagrees with the version inpyproject.tomlstops before any upload. - The build installs the built Python distributions in isolated environments.
tests/smoke_test.pyopens a real MCP stdio client against their console entrypoint; it does not import an editable checkout or substitute fake provider checks for the package check. - npm ships only a launcher and package documentation. It starts
uvx tapebasis, forwarding stdio, arguments and environment. It is not a second TypeScript MCP server. Node.js 18 or newer and uv are required on the user's machine. - A tag build produces the wheel, sdist, npm tarball and OCI image once. The publish job downloads those tested artifacts and verifies their SHA-256 checksums instead of silently rebuilding them.
- Publication is sequential within the approval-gated publish job: PyPI, then npm, then GHCR. Each
step must succeed before the next one starts. Only after those package versions resolve does the
job publish
server.jsonto the MCP Registry. A registry has no transaction that can retract an earlier successful upload automatically when a later step fails. -
publish-image.ymlretains its filename but only calls the validation workflow. Main, pull requests and manual runs have no registry publication. An approved release tags its tested imagelatest; there is no moving main-branch image.
Create one protected environment named release. Restrict its deployments to v* tags and require
maintainer review before deployment. Gate all registry uploads through this one approval. Do not
create or rely on separate pypi, npm, ghcr or MCP environments; those names would not match the
workflow. No registry publication secrets need to be stored in the environment.
Protect v* tags against unauthorized creation or modification. The workflow cannot infer who created
a tag, so environment approval and tag protection are the human release controls.
Use PyPI's pending trusted publisher before the first release; no existing project or persistent API token is needed.
| Field | Value |
|---|---|
| PyPI project name | tapebasis |
| Owner | giraygokirmak |
| Repository | tapebasis |
| Workflow name | release.yml |
| Environment name | release |
The publish job has id-token: write and uses uv publish --trusted-publishing always. Do not
configure UV_PUBLISH_TOKEN, a PyPI API token, or username/password publishing in CI. A missing or
mismatched pending publisher is an account setup failure and stops at PyPI.
npm requires the package to exist before a trusted publisher can be configured on its package settings page. That prevents the very first package creation from being authenticated by its as yet unconfigured OIDC publisher. This is a bootstrap limitation, not a permanent token requirement.
- Verify
npm view tapebasis versionreports that the package does not exist. If someone else has claimed it, choose another available unscoped name and updatepackage.json, the lockfile,server.json, install examples and release checker together. Do not publish over another package. - Run the full test and package gate from a clean checkout at the intended release commit.
- With the npm account that will own the package, run
npm logininteractively. Then publish the already tested tarball withnpm publish ./tapebasis-1.0.0.tgz --access public --otp=<current-code>. Complete interactive two-factor authentication as prompted. This is an explicit maintainer action, not a workflow invocation. Never put a persistent npm token in a GitHub environment or log it. Do this bootstrap before thev1.0.0tag so PyPI does not upload first and then stop at an unprovisioned npm account. After bootstrap, setTAPEBASIS_NPM_BOOTSTRAPPED=1as a release environment variable on GitHub. This does not publish anything itself; it records that the manual step completed. Keep the variable unset on forks and before bootstrap. The tag job must not callnpm publishfor this already published version. - In the npm package settings, choose Trusted publishing, then GitHub Actions, with organization
or user
giraygokirmak, repositorytapebasis, workflow filenamerelease.yml, and environmentrelease. Allow directnpm publishfor this workflow. The case and filename must match exactly. npm requires Node.js 22.14.0 or newer and npm 11.5.1 or newer. A new trusted publisher configuration must complete its first successful publish within 2 days, or it expires and must be recreated. - The workflow uses GitHub-hosted Node.js 24 and its bundled npm CLI. It exchanges GitHub's OIDC
identity for a short-lived publish credential; no
NPM_TOKEN,NODE_AUTH_TOKEN, or persistent automation token is used. On a public repository publishing a public package, trusted publishing creates provenance automatically. - Prefer restricting ordinary token publishing in npm after the trusted publisher is working. Remove
the bootstrap credential from the local machine as usual with
npm logout.
The npm step deliberately fails rather than falling back to a stored token. Bootstrap npm once as above, then subsequent tags use trusted publishing. If the version already exists without the release marker, the job stops. With the marker, it requires the registry's version and SHA-512 integrity to match the tested tarball instead of uploading an existing version again. Any other version is published through OIDC; a mismatch stops GHCR and MCP Registry publication. Do not regard a partial release as completed or retry it without reviewing each registry.
The same approved publish job uses the built-in GITHUB_TOKEN with packages: write and downloads the
tested OCI archive. It publishes 1.0.0, 1.0, 1, and latest for this release. It does not publish
a v-prefixed image tag. After the first GHCR publication, set the container package's visibility to
public if unauthenticated pulls are intended, then confirm docker pull works without credentials.
Creating the environment does not create a package or make it public.
No long-lived container-registry secret is needed. An older main-image package can continue to exist; release automation neither creates nor changes its visibility.
The server name is io.github.giraygokirmak/tapebasis. package.json carries the matching mcpName
marker, README carries the PyPI mcp-name marker, and the OCI image carries the corresponding ownership
label. These markers are validated before publication, but do not prove that registry publication has
already happened.
The verified mcp-publisher executable logs in with github-oidc. Publishing from this repository's
GitHub workflow proves the matching GitHub namespace; no separate MCP Registry account or persistent
registry token is needed. The registry currently supports the official npm and PyPI registries used by
server.json, and hosts metadata rather than package artifacts. The workflow runs mcp-publisher validate before building, then publishes only after PyPI, npm and GHCR have succeeded and their version
endpoints are readable.
-
Run
git fetch --tagsand inspect existing tags and the intended target commit. -
Update the same semantic version in
pyproject.toml,src/tapebasis/__init__.py,package.json, the root andpackages[""]entries ofpackage-lock.json,server.json, and its npm and PyPI package entries. Update registry ownership markers only if the server identity also changes. -
Run
PATH=<uv-install-directory>:$PATH scripts/quality-gate.sh --commitlocally after installing the project and its development extras in.venv. Omit thePATH=prefix when uv is already installed. On Python 3.10 the project installstomli, socheck_release.pyparses TOML with the same implementation used by Python 3.11 and later rather than accepting malformed metadata. Addnpm test,npm run check, andnpm pack --dry-runfor launcher changes. The full test gate already performs the real build, installation and MCP smoke tests. -
Land the tested commit on main. Do not tag an uncommitted working tree, and do not tag merely to make red CI retry. The gate does not tag or publish anything itself. Its pre-push wiki mirror runs in an independent child repository with inherited
GIT_*repository bindings removed, and records its sync stamp in the source worktree's actual Git directory. A successful source push therefore cannot turn the wiki child commit into a main-branch commit. The production wiki URL is fixed;TAPEBASIS_WIKI_REPOSITORYexists only to redirect the hermetic Git-context regression test to a temporary local wiki. Do not set it for a normal release push. -
Check the candidate without a previous-ref comparison for the first release:
python scripts/check_release.py --tag v1.0.0
For a later release, compare against an existing previous tag. For example:
python scripts/check_release.py --tag v1.0.1 --against v1.0.0
--againstrequires the git ref to resolve, its version to be valid, and the new version to be newer. -
Have a maintainer create and push one
v*tag matching the declared version. Do this only after PyPI is provisioned and npm bootstrap is deliberately planned or already completed. -
Watch Validate, Build release artifacts and Publish. Approve the
releasedeployment only after checking the successful tests, artifacts and tag. The publish job records no successful publication until all steps finish. Branch runs and pull requests never get an upload credential. -
Check each registry, including the MCP Registry search endpoint, after the job reports success:
curl 'https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.giraygokirmak/tapebasis'
Investigate the workflow log and each registry before retrying. PyPI and npm reject republishing an
existing version with different contents; increment versions when a new artifact is required. GHCR tags
can move, so an operator must confirm a release retry does not unexpectedly overwrite a previous one. A
tag mismatch, tests, distribution smoke test, npm launcher test, package inspection, checksum, missing
artifact or earlier publish failure is always release-stopping. There is no continue-on-error
publication fallback and no always() job bypass. MCP Registry failure comes last, so inspect all
package uploads before deciding how to complete that release.
The OCI archive layout is unit-tested locally and the release workflow builds the real image in CI. A local environment without a working Docker daemon cannot claim to have completed that image build.
One local npm stdio run with MCP Python SDK 1.30.0 completed package installation and tool discovery,
then reported BrokenResourceError while the SDK's stdout reader was shutting down. Targeted and
complete gate reruns passed without changing the server or suppressing that exception. The tests contain
no retry or error allowlist. Treat a recurrence as a failed release gate and capture the child's stderr;
do not describe that single observed teardown failure as fixed by a successful rerun. An upstream SDK
fix requires a separate, reproducible dependency change rather than hiding it in the release launcher.
- Development: local test and quality-gate commands
- Docker: release image tags, build and deployment
- Design Decisions: why credentials and publication are separated