# Release > Release automation skill for version bumping and tagging. Use when creating a new release, bumping version, tagging release, pushing release tag, or synchronizing version numbers across files. Handles package.json, README.md, SKILL.md, Dockerfile, and docker-compose files. Use when this capability is needed. - Skill: `tomevault-io/release-100` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/release-100` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/release-100/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: DevOps & Infra - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/release-100 --- # Release Automation Skill ## Purpose Automate the release process for the Madeinoz Knowledge System, including version synchronization across all files, git tagging, and triggering the CI workflow. ## When to Use Use this skill when: - Creating a new release (major, minor, or patch version) - Bumping the version number - Tagging a release commit - Pushing a release to trigger CI workflow - Synchronizing version numbers across multiple files ## Version Sync Locations The following files MUST be updated with the new version: ### Primary Version Files 1. **package.json** (line 3) ```json "version": "X.Y.Z" ``` 2. **docker/Dockerfile** (line 8) ```dockerfile LABEL version="X.Y.Z" ``` 3. **README.md** (line 6) ```yaml pack-id: madeinoz67-madeinoz-knowledge-system-core-vX.Y.Z ``` 4. **src/skills/SKILL.md** (line 3) ```yaml version: X.Y.Z ``` ### Production Docker Compose (Manual Update) 5. **src/skills/server/docker-compose-production.yml** (line 85) ```yaml image: ghcr.io/madeinoz67/madeinoz-knowledge-system:X.Y.Z ``` **Note:** All other docker-compose files use `:latest` tag and do NOT need updates. ### Do NOT Edit - **CHANGELOG.md** - Auto-generated by git-cliff workflow - Modifying this file will conflict with automated changelog generation ## Pre-Release Checklist Before creating a release, verify: ```bash # 1. Check you're on main branch git branch --show-current # Should output: main # 2. Pull latest changes git pull origin main # 3. Verify working tree is clean (no uncommitted changes) git status # Should show: "nothing to commit, working tree clean" # 4. Verify latest CI passed gh run list --limit 1 # Check status is "completed success" ``` ## Release Workflow ### Step 1: Update Version Numbers Manually edit the version files listed above. For example, bumping from `1.8.0` to `1.9.0`: ```bash # Edit package.json # Edit docker/Dockerfile # Edit README.md # Edit src/skills/SKILL.md # Edit src/skills/server/docker-compose-production.yml ``` ### Step 2: Commit Version Changes ```bash git add package.json docker/Dockerfile README.md src/skills/SKILL.md src/skills/server/docker-compose-production.yml git commit -m "chore: bump version to X.Y.Z" ``` ### Step 3: Create Annotated Tag ```bash # Single-line description git tag -a vX.Y.Z -m "Release vX.Y.Z" # OR multi-line description (opens editor) git tag -a vX.Y.Z ``` In the editor, use this format: ``` Release X.Y.Z Summary of what's in this release: - Feature one - Bug fix two - Improvement three ``` ### Step 4: Push Tag to Trigger CI ```bash git push origin vX.Y.Z ``` This triggers the CI workflow which: - Generates changelog from git-cliff - Updates CHANGELOG.md on main branch - Builds and pushes multi-arch Docker image to GHCR - Creates GitHub Release with formatted release notes - Deploys documentation to GitHub Pages ## Verification After pushing the tag: ```bash # Watch workflow run gh run watch # Confirm release created gh release view vX.Y.Z # Verify Docker image on GHCR # https://github.com/madeinoz67/madeinoz-knowledge-system/pkgs/container/madeinoz-knowledge-system ``` ## Common Pitfalls ### DO NOT Use `gh release create` Directly ❌ **Wrong:** `gh release create vX.Y.Z --notes "Release notes"` This creates the tag via GitHub API without triggering the CI workflow. The release job will never run, leaving a broken release (no Docker image pushed, no docs deployed). ✅ **Correct:** `git push origin vX.Y.Z` This triggers the `push` event for the tag, which runs the CI workflow. ### DO NOT Edit CHANGELOG.md ❌ **Wrong:** Manually editing CHANGELOG.md This file is auto-generated by git-cliff during the CI workflow. Manual edits will be overwritten. ✅ **Correct:** Use conventional commit messages. The changelog is generated from commit history. ### Version Inconsistency Ensure all version files use the exact same version string: - package.json: `"version": "1.9.0"` - Dockerfile: `LABEL version="1.9.0"` - README.md: `pack-id: madeinoz67-madeinoz-knowledge-system-core-v1.9.0"` - SKILL.md: `version: 1.9.0` ### Production Compose Version The `docker-compose-production.yml` file pins specific versions. Remember to update this file when releasing, as it's used for production deployments. ## Release Types | Type | Example | When | |------|---------|------| | **Major** | 1.8.0 → 2.0.0 | Breaking changes | | **Minor** | 1.8.0 → 1.9.0 | New features, backward compatible | | **Patch** | 1.8.0 → 1.8.1 | Bug fixes, small improvements | ## Quick Reference ```bash # Full release workflow (replace X.Y.Z with actual version) # 1. Edit version files vim package.json docker/Dockerfile README.md src/skills/SKILL.md src/skills/server/docker-compose-production.yml # 2. Commit changes git add package.json docker/Dockerfile README.md src/skills/SKILL.md src/skills/server/docker-compose-production.yml git commit -m "chore: bump version to X.Y.Z" # 3. Create annotated tag git tag -a vX.Y.Z -m "Release vX.Y.Z" # 4. Push tag to trigger CI git push origin vX.Y.Z # 5. Verify gh run watch gh release view vX.Y.Z ``` ## Related Documentation - [CLAUDE.md](../../CLAUDE.md) - Release checklist (critical section) - [.github/workflows/ci.yml](../../.github/workflows/ci.yml) - CI workflow definition - [docs/reference/releases.md](../../docs/reference/releases.md) - Release documentation --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/madeinoz67) — claim your Tome and manage your conversions.