Develop and deploy (git-free, dev-and-deploy)

Git-free develop-and-deploy chain: specs, workspace and block release, push, pull all instances, action install. Canonical path /docs/polycrate/dev-and-deploy/.

Polycrate versions *.poly, runs actions, and installs packages. Git is not a Polycrate process concern. An existing tag vX.Y.Z does not fail or warn at finalize.

This page is the canonical develop-and-deploy chain. Details for Workspaces, Blocks, and Actions stay on those pages. Git workflows are optional — see Git integration.

Six steps

  1. Specs to done — Open Questions must be empty (HTML comments count as empty).
  2. Workspace SDD release — family workspace, ops release_create, release_update, release_finalize, release_status. Changelog message and RELEASENOTE highlights are required at finalize. Zero assigned specs is a warning, not a fail.
  3. Release pre_actions / post_actions run as part of finalize.
  4. Block SDD — family block, ops release_create, then release_update (CHANGELOG message; app_version if the block carries an app image), then release_finalize. There is no block bump.
  5. block op push.
  6. Downstream: block op pull with a version writes from: on every workspace instance of that FQBN (unwrap once). Then action op run with action install. Do not write or validate image_tag.

CLI counterparts (canonical surface):

polycrate spec update <id> --set status=done
polycrate release create X.Y.Z
polycrate release update X.Y.Z --set type=feat --set message="..."
polycrate release finalize X.Y.Z
polycrate block push <block>
polycrate block pull <registry/org/name:version>
polycrate run <block> install

--workspace / -w must be an absolute path. Relative -w is a hard fail.

MCP

One server: polycrate mcp. Six tools, no aliases, no session_id. Pass an absolute workspace on mutating ops. Never relative -w.

  • sdd — list, inspect, create, update_meta, update_section, lint, format
  • docs — schema (local), guide (embedded), get/search (Backplane public; no scrape; no Bearer)
  • hub — inspect_block, list_versions, list_blocks, info, cli_*
  • workspace — release_*
  • block — release_* plus push and pull (not package/consume)
  • action — run

sdd.update_section writes section bodies only (no H1/H2/frontmatter). File-edit of spec bodies remains allowed. Both end in lint.

The CLI Manual (polycrate spec manual) is optional SSOT. There is no required get_manual ritual.

More on MCP integration: MCP Server.

Docker registry auth

Do not mount ~/.docker/config.json. Inject from the process environment into the action container:

  • DOCKER_REGISTRY_HOST
  • DOCKER_REGISTRY_USER
  • DOCKER_REGISTRY_PASSWORD

CARGO_* is playbook fallback only.

Hard fail

Relative -w, invalid ids, H1/H2 in an update_section body, non-empty Open Questions on sdd.update_meta status=done or workspace finalize of assigned specs, empty changelog message, empty highlights.

Not a gate

Red spec verify, dirty git, zero specs on a release, existing git tag vX.Y.Z.

What Polycrate does not sell as process

  • Git tag as source of truth
  • workspace sync as a release step
  • block bump
  • CI-first (CI consumes the same chain)
  • image_tag as a product check

VCS remains your habit — not the Polycrate process. See Git integration.

Next