Devops Bmk

devops-bmk

Install, configure and use bmk -- a cross-OS CLI task runner that orchestrates a project's build, test, clean, release and custom staged commands from a single thin Makefile. It runs a pure-Python stage runner (no shell/PowerShell scripts), so the same commands work natively on Linux, macOS and Windows. Source and docs: https://github.com/bitranox/bmk

Mental model: you install bmk once with uv to bootstrap, drop a bmk-managed Makefile into the project, and from then on drive everything through make <target>. The Makefile keeps bmk itself installed (bmk alone, in uv's own tool dir, shared by every project) and delegates to it. Your project's dependencies live in your project's own .venv, which bmk provisions separately. Each command runs a pipeline of stages grouped by an order number: stages run sequentially and fail-fast; stages sharing the same order run in parallel.

When to use

• Setting up bmk in a new or existing project (uvx bmk install).
• Running the standard dev loop: make test, make push, make bump-patch, make release, make ship.
• A tool the pipeline needs is missing (shellcheck, shfmt, pwsh, ...) -> bmk ensure.
• Output is empty/terse and you want the full verbose run -> --human / BMK_OUTPUT_FORMAT=text.
• Customising the config (profiles, --set overrides) or adding a custom pipeline.

Not for: developing bmk's own source (that is the bmk repo's CLAUDE.md/CONTRIBUTING.md). This skill is about using bmk as a task runner in any project.

1. Install

uv is the only prerequisite. You never install bmk yourself: run bmk install once, ephemerally, to drop the Makefile in - from then on the Makefile installs and manages bmk per project.

# Install uv first if needed (https://astral.sh/uv)
curl -LsSf https://astral.sh/uv/install.sh | sh          # macOS/Linux
# Windows (PowerShell): powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

cd your-project
uvx bmk install            # writes the Makefile; installs nothing permanently
make test                  # from here on, everything goes through make

You do not need uv tool install bmk yourself: once the Makefile is in place it keeps bmk installed for you (see below). uvx bmk install is only the bootstrap that writes the Makefile.

bmk's env holds bmk alone, and is shared

Once a project has the Makefile (section 2), every make first runs

uv tool upgrade bmk        # falls back to `uv tool install --reinstall --force` if damaged

which keeps bmk on its own in uv's default tool dir and runs it from there ($(uv tool dir --bin)/bmk). Note what is not in that command: your project. The env holds bmk's toolchain and nothing of yours, which is exactly why one env can serve every repo on the machine - there is nothing project-specific in it to collide.

Do not add --with . / --with-editable ".[dev]", and do not redirect it per project with UV_TOOL_DIR. Resolving bmk together with a project is what caused, in order: one of your dependencies capping one of bmk's and silently pinning bmk to an ancient release; a yanked transitive making bmk itself uninstallable; and the tests running in that co-resolved env while pyright and pip-audit inspected your real .venv, so the suite and the audit described different environments.

• It runs on every make, deliberately, so a new bmk release is picked up with nothing to remember and no version marker to go stale. Do not gate it behind a stamp file: make would skip it and the env would silently pin itself to whatever bmk it first saw.
• It upgrades; it does not reinstall on the common path. uv tool upgrade revalidates the index on every run and is a near no-op when bmk is already current. The unconditional --reinstall --force it replaced tore the env down on every make - and because the env is shared, that deleted the site-packages out from under a bmk still running in another repo. --refresh is not needed and uv rejects it (exit 2); offline it simply answers "Nothing to upgrade".
• The rebuild waits for the bmk processes using that env. Every bmk holds a shared lock on the tools root for its lifetime; the upgrade takes the same lock exclusively. Readers do not exclude each other, so two repos still gate at the same time - only a mutation waits. The wait is bounded: an upgrade that cannot get the lock is skipped (the next make takes it), while a repair that cannot get it fails rather than continuing on a damaged env. Set BMK_TOOL_LOCK=0 to disable it. You no longer need a caller-side lock (a flock around make, a coordinator mutex) to stop two repos colliding here - and a caller-side one is worse, because it serialises whole gates where bmk serialises only the provisioning.
• Two writers stay out of reach by construction: a repo whose Makefile predates this is unguarded until its next make regenerates it, and a hand-run uv tool install bmk always is. So when a command fails and the env turns out to have been replaced mid-run, bmk says so on stderr rather than leaving an ImportError inside its own dependencies to look like a flake.
• Right after a release there is a brief window where uv's index still reports only the previous version; the next make picks the new one up.

The project venv .venv

This is where your dependencies live. Before any command that touches the Python environment (test, push, deps, build, ...), bmk creates the project's own .venv if it is missing and syncs it to pyproject.toml. pytest, pyright and pip-audit all resolve that venv, never bmk's own and never whatever venv happens to be active in your shell -- so the environment you test in, type-check in and audit are one and the same, and no project can quietly install its dependencies into an environment it does not own.

One bmk provisions a venv at a time. The sync is serialised by an exclusive lock scoped to that one venv path, so a subagent's make test beside yours - or test-all beside test - can no longer reinstall packages under a running gate. Unguarded, the loser did not crash: provisioning degrades rather than raising, so it silently tested a different environment. BMK_VENV_LOCK_TIMEOUT (default 600s) bounds the wait and BMK_VENV_LOCK_DIR says where the lock files live (outside every repository). Because the scope is one venv path, test-all still provisions its versions in parallel.

Which Python it is built on: the newest your classifiers declare, at its latest patch.

[project]
requires-python = ">=3.10"                     # a FLOOR - says nothing about the newest
classifiers = [
  "Programming Language :: Python :: 3",       # ignored: no minor
  "Programming Language :: Python :: 3.10",
  "Programming Language :: Python :: 3.14",    # <- .venv is built on 3.14, latest patch
]

The classifiers are where a project states the versions it supports, and your CI workflow already builds its test matrix from the same entries - so your venv and your CI matrix cannot drift apart about what "newest supported" means. requires-python cannot serve: >=3.10 never names the top.

Before those commands bmk runs uv python install <X.Y> and uv python upgrade <X.Y>. Both matter: install fetches a version you just added to the classifiers, and upgrade is what moves an already-installed minor onto a newer patch (install alone keeps the version it has). Current and offline, this costs about 0.1s.

A new patch costs you nothing. uv builds a venv against the minor alias, so uv python upgrade moves your existing venv onto the new patch by itself; bmk checks the interpreter, sees it is current, and does nothing. (pyvenv.cfg still names the old patch after that - it is written once at creation. bmk asks the interpreter, not that text, so it does not rebuild a venv uv has already migrated.)

A minor change is the one that cannot be done in place: move 3.14 to 3.15 in your classifiers and the venv is rebuilt. The path never changes, so nothing pointing at it breaks. If uv cannot say what it would provide, your venv is left alone; bmk never rebuilds on a guess. Declare no :: Python :: X.Y classifier and bmk picks no version at all - uv's default stands.

The same classifiers drive make test-all: it provisions one .venv-<minor> per declared version and runs pytest + pyright in each, in parallel, so you can reproduce CI's matrix locally before you push. Plain make test stays on the newest version only; with no :: Python :: X.Y classifier, test-all tests the default interpreter once and prints a WARNING naming the version it used.

The sync is exact and upgrading: it removes packages the manifest no longer asks for and re-resolves the ones it does. A venv left to drift makes the gates lie -- pip-audit reports CVEs for packages the project does not actually resolve, while the real resolution stays hidden. The trade-off: packages you installed into the venv by hand do not survive a sync.

Set UV_PROJECT_ENVIRONMENT when one checkout is used from more than one OS (a share mounted on both Linux and Windows): a single venv cannot serve both, so give each its own (e.g. .venv-win). If provisioning fails, bmk falls back to its own interpreter rather than failing the command.

clean does not delete the venv (that would throw away what bmk just built and force a full re-resolve); make clean-all removes every .venv* alongside the build artifacts when you do want them gone. bmk also keeps venvs out of git: it adds a single .venv* glob to .gitignore when nothing already ignores them (one line covers .venv and every .venv-<minor> the matrix creates), and if git is tracking a venv it drops it from the index (git rm --cached) while leaving the files on disk, announcing that it did. A tracked venv would otherwise show thousands of modified files after every sync.

2. Bootstrap the Makefile

uvx bmk install    # writes / updates a bmk-managed Makefile in the current directory
                   # (`uvx` so this works before bmk is on PATH; plain `bmk install` once it is)
make test          # from now on, drive everything through make

The Makefile keeps bmk installed and your project's .venv synced to pyproject.toml, so once it is in place you rarely call bmk directly. On Windows you still need a make implementation. On a non-admin box install it user-scope with winget install --id ezwinports.make -e --scope user (run make from Git Bash so the Makefile's SHELL := /bin/bash resolves); choco install make needs an elevated shell. bmk itself needs no shell.

3. Everyday commands

Drive these with make <target> (or call bmk <command> directly). Arguments after the target are forwarded (e.g. make push fix login bug). Most have short aliases.

What version bump and release accept, and what they produce

[project].version may be any canonical PEP 440 version - 1.2.3, 1.2.3a1, 1.3.0b2, 1.2.3rc1, 1.2.3.dev4, 1.2.3.post1, 1.0, 1.2.3.4, 1!2.0.0. That is what hatchling builds and PyPI accepts, so bmk does not narrow it to X.Y.Z.

release accepts every one of those - a pre-release is NOT refused for being one - and tags v + the version string verbatim: 1.3.0b2 tags v1.3.0b2. Its only version check is the two shapes below.

Two shapes are refused, each printing the fix:

A bump always lands on a plain three-part release, and FINALIZES a non-final version rather than stepping past it - so the release an rc was rehearsing stays reachable:

A post release is FINAL, which is why 1.2.3.post1 increments. The epoch survives a bump; pre, dev, post and local segments are dropped. bmk has no command that CREATES a pre-release - write one into pyproject.toml yourself, then bump to finalize it.

If the project ships a Claude Code skill, two version rules apply and neither is optional. An install re-fetches a skill only when .claude-plugin/plugin.json changes version, so a release that edits skills/ without moving that version ships the code and leaves every install on the old skill - no error, nothing to notice, and the skill then documents behaviour the tool no longer has.

• bump, push and release raise plugin.json to the package version whenever it lags, and never lower it. The plugin version can legitimately be AHEAD, because a skill ships more often than the package it documents; writing the package version there unconditionally would move an install backward to a version it already had.
• A non-final package version (1.2.0rc1) is NOT written into plugin.json. Ordering it is not the problem; that manifest is read by Claude Code's marketplace machinery and is only ever seen carrying a plain X.Y.Z. The final release that follows carries the skill.
• release refuses outright when skills/ changed since the last tag and the plugin version did not move. That is the one case the sync cannot fix: the two versions were already equal, so there was nothing to raise. Bump plugin.json yourself and release again.

Run bmk --help or bmk <command> --help for the complete, current list (there are also config, config-deploy, send-email, run, info, logdemo, ...).

4. Output format: JSON by default

bmk test / bmk testintegration default to machine-readable JSON and stay silent on success -- tool output is captured and shown only when a stage fails. To get the full verbose run:

• make test-human / any command with --human, or
• set BMK_OUTPUT_FORMAT=text.

Precedence: --human (forces text) > BMK_OUTPUT_FORMAT > default (json). If a run "does nothing visible", that is JSON mode succeeding -- add --human to watch it work.

5. Missing external tools: bmk ensure

Some pipeline stages call external tools (git, pwsh, shellcheck, shfmt, bashate, PSScriptAnalyzer). If a run complains one is missing:

The .sh shell-lint gate's settings (know these before "fixing" a diff). bmk runs shfmt -i 4 -ci and bashate --max-line-length 120. Both matter: matching shfmt's indent but omitting -ci (indent switch cases) still yields a rejected diff, and bashate reads NO config file - not pyproject.toml, not .bashaterc - so without the explicit flag it falls back to its 79-char default and flags lines the project considers fine. Reformatting to your local defaults instead of these values is the usual cause of "passes locally, fails the gate".

Before bmk 3.13.2 the gate's file discovery also descended into a NESTED git worktree and linted another branch's checkout as part of yours. The tell is a lint error naming a path you do not recognise; upgrade, or move the nested checkout outside the tree.

make ensure                 # install everything missing for this OS
bmk ensure --dry-run        # just report what would be installed
bmk ensure --strict         # non-zero exit if anything is still missing

6. Configuration and custom pipelines

Layered config is merged from defaults + files + env by lib_layered_config. Inspect and override:

make config                                   # show the merged config
bmk --profile production test                 # load a named profile
bmk --set email.from_address=me@example.com test   # one-off override (repeatable)

Custom pipelines: add, remove or replace stages under [tool.bmk.pipelines.<prefix>] in the project's pyproject.toml (or bmk_makescripts/stages.toml). Each stage is a declarative argv list. Run one with bmk custom <name> / make custom <name>. This is the only override mechanism.

Test markers: what make test runs. make test runs pytest -m "not <exclude-markers>", where exclude-markers comes from [tool.scripts.test].exclude-markers and defaults to "integration". So out of the box make test runs your unit tests AND local_only tests and skips integration; make testintegration runs -m integration; a CI job typically runs pytest -m "not local_only". The local-vs-CI difference is intentional - make test is not meant to be identical to CI.

Raise exclude-markers only to skip MORE from make test - e.g. a project whose local_only tests MUTATE the host and are unsafe on a real dev machine can tag them mutating and set exclude-markers = "mutating" (a common project-specific marker). Do NOT set it to "match CI" - that drops the fast local coverage local_only exists to provide.

bmk runs pytest in this project's own .venv (section 1), which it syncs with the project's [dev] extra, so [dev]-only test-import deps (fakes, test-support libraries, property-test helpers) are present. That is the same venv pyright and pip-audit resolve, so the suite, the type check and the audit all describe one environment.

Proving a gate actually ENFORCES (two wrong readings of a green make test)

Two independent readings of a green make test are wrong, and both come from bmk's stage table rather than from your code.

1. ruff --fix rewrites the tree before any checker runs. In the stage registry ruff_fix_apply is order 30, while bandit, lint_imports, pip_audit, pyright, pytest and ruff_lint are ALL order 40. So a probe you plant to prove a checker fires can be DELETED before that checker ever sees it: a bare unused import is removed at stage 30 and the gate greens having never examined it. To plant a probe that survives, BIND the imported name so --fix cannot remove it, and keep the binding after the last import or E402 fires instead.

2. An undeclared tool does NOT mean its stage is skipped. The registry lists every stage unconditionally, and context._prepend_tool_bin_to_path deliberately puts bmk's OWN venv bin dir first on the child PATH so bare-name stages resolve to bmk's pinned toolchain rather than to whatever sits first on your PATH. lint_imports_argv returns a bare ["lint-imports"]. So a floor declared in your pyproject.toml never governs the gate, and a genuinely missing tool fails LOUDLY with FileNotFoundError rather than silently skipping. Do not file a defect against a stage on the theory that it was skipped.

The pinning differs per tool, which decides which environment a stage actually used: pytest runs on ctx.python_cmd, pyright is pinned via --pythonpath, and lint-imports is pinned to nothing.

Prove it rather than reasoning about it: run the arm where the check must FAIL, and require the gate to go red. A gate that has only ever passed has not been shown to gate. See bitranox:process-test-design.

Troubleshooting

Further reading

Self-contained above; for depth, read these (WebFetch the URL, or the local clone if you have it):