Create a versioned release — commit, tag, push, and deploy to servers. Use when the user wants to release, deploy, publish, or push a new version.
Create and deploy versioned releases of the Memory platform. Handles version bumping, OpenAPI spec updates, git tagging, CI triggering, and server upgrades.
All components share a single version derived from the git tag:
Git tag v0.X.Y
├── CLI binary v0.X.Y (built by CI)
├── Docker image memory-server:v0.X.Y (built by CI)
├── API /health returns "v0.X.Y" (ldflags at build time)
└── OpenAPI spec info.version = "0.X.Y" (annotation in main.go)
CI Workflows triggered by v* tag push:
cli.yml — Builds CLI binaries for 8 platforms, creates GitHub Releasepublish-self-hosted-images.yml — Builds & pushes Docker image, uploads images-ready.txt sentinel to releaseCheck the current version:
git tag --sort=-v:refname | head -3 # Latest tags
cat VERSION # VERSION file
Bump accordingly (patch for fixes, minor for features).
IMPORTANT: Only stage files related to the changes being released. Do NOT include unrelated uncommitted work.
git add <changed-files>
git commit -m "fix/feat: description of changes"
Three places need updating:
VERSION file (root):
echo "0.X.Y" > VERSION
OpenAPI spec annotation in apps/server/cmd/server/main.go:
// @version 0.X.Y ← line 4
Regenerate Swagger docs (if OpenAPI version changed):
nx run server:swagger
If swagger generation fails or is unavailable, skip it — the version annotation is what matters for the tag, and CI will regenerate docs during the Docker build.
Commit the version bump:
git add VERSION apps/server/cmd/server/main.go apps/server/docs/swagger/
git commit -m "chore: bump version to 0.X.Y"
Before tagging, verify the build is clean:
go build ./... # must succeed — fix any compile errors first
git status --short | grep "^?" # check for untracked files that should have been staged
If go build ./... fails, do not tag. Fix the errors and commit first.
If there are untracked files related to the release (e.g. generated docs), add and commit them now.
git tag v0.X.Y
git push origin main --tags
This triggers CI which takes ~5-10 minutes to:
cli.yml — the Release appears in GitHub only after CI completes, not immediately after git tag)ghcr.io/emergent-company/memory-serverimages-ready.txt sentinel when Docker image is readyNOTE:
git tag+git push --tagsdoes NOT immediately create a GitHub Release. The Release is created by thecli.ymlCI workflow. Monitor progress with:gh run watch
If the user wants to deploy to a specific server:
Option A: SSH and run upgrade command (if memory CLI is in PATH on the server):
ssh root@<server> "memory upgrade"
Option B: SSH and pull directly (if CLI is not installed on the host):
ssh root@<server> "cd ~/.memory/docker && docker compose pull && docker compose up -d"
Option C: Wait for user to upgrade manually
NOTE: The
memory upgradecommand checks for theimages-ready.txtsentinel in the GitHub Release before proceeding. If CI hasn't finished yet, the upgrade will fail. Either wait or use--forceflag.
ssh root@<server> "curl -s http://localhost:3002/health | jq '.version'"
# Should return "v0.X.Y"
| Server | SSH | Notes |
|---|---|---|
| your-server | ssh root@your-server | Standalone deployment, DB container: emergent-db, DB user: emergent |
| Item | Location |
|---|---|
| VERSION file | /root/emergent.memory/VERSION |
| OpenAPI annotation | apps/server/cmd/server/main.go line 4 |
| Swagger docs | apps/server/docs/swagger/ |
| CI: CLI + Release | .github/workflows/cli.yml |
| CI: Docker image | .github/workflows/publish-self-hosted-images.yml |
| Dockerfile | deploy/self-hosted/Dockerfile.server |
| Upgrade command | tools/cli/internal/cmd/upgrade.go |
| Versioning docs | apps/server/VERSIONING.md |
| Docker registry | ghcr.io/emergent-company/memory-server |
@version annotation updated in main.gogo build ./... passes (no compile errors)git status --short | grep "^?")git tag v0.X.Ygit push origin main --tagsgh run watch)