/gaia-release

user-facing
Category:
Deployment
Lifecycle phase:
5 -- Deployment
Arguments:
[patch|minor|major|none|X.Y.Z] [--prerelease rc] [--strip-prerelease] [--modules mod1,mod2]* [--dry-run]

* --modules is documented in SKILL.md but not yet implemented in scripts/version-bump.js — see Arguments section.

What it does

/gaia-release executes the GAIA framework release procedure: version bump, commit, tag, push, and GitHub Release creation. It wraps the version-bump script and enforces the main-only release branch policy. Always run with --dry-run first to preview changes.

When to use it

  • You are explicitly cutting a manual release after merging a sprint PR to main.
  • You are performing a hotfix release via the hotfix/{ticket-id} branch convention and need the tag+publish ceremony.
  • You need to promote a release candidate to its final stable version (--strip-prerelease).

Scope clarification

The primary release path is automated via release.yml (GitHub Actions). When code merges to main, the workflow detects qualifying commits under plugins/gaia/, computes the semver bump, opens a release PR, and -- on merge of that PR -- creates the tag and GitHub Release automatically. As of PR #771, the commit-classification range uses a tag-based anchor (git describe --tags --abbrev=0 --match 'v*') instead of the previous github.event.before SHA, which resolves the symptom where the version-bump PR sometimes never opened after squash-merge.

/gaia-release remains in the Phase-5 deployment catalog for explicit manual invocation only. Typical uses: hotfix releases, RC promotions, and resolving version drift between package.json and the config. The framework does not auto-suggest /gaia-release after staging-to-main merges.

Prerequisites

  • You must be on the main branch with a clean working tree.
  • The sprint PR must already be merged. Releases happen only after sprint merge.

Arguments

NameTypeRequiredDefaultDescription
Bump specifier patch | minor | major | none | X.Y.Z Yes -- Standard semver bump, or none to increment only the RC counter (requires existing -rc.N suffix), or an explicit version string.
--prerelease rc Flag No Off Turn the bump into an RC prerelease (e.g., 1.127.2 becomes 1.128.0-rc.1 for a minor bump).
--strip-prerelease Flag No Off Drop the -rc.N suffix without changing version numbers. Promotes an RC to its final stable cut.
--modules mod1,mod2 Comma-separated list No -- Also bump per-module config.yaml and manifest entries. Valid modules: core, lifecycle, dev, creative, testing, or all.

Implementation note: Currently documented in SKILL.md but not implemented in scripts/version-bump.js. Passing --modules has no effect on the bump. Tracked as upstream SKILL.md drift; will be removed from docs once either implementation lands or SKILL.md is corrected.
--dry-run Flag No Off Print the planned changes and exit without writing. Use this first on every release.

How to invoke

/gaia-release patch --dry-run
/gaia-release minor --prerelease rc
/gaia-release --strip-prerelease

What it does step by step

  1. Verify main branch Confirms you are on main with a clean working tree. Halts if not.
  2. Dry-run the bump Runs the version bump in preview mode showing the current version, new version, and files that would change.
  3. Execute the bump Updates package.json and the framework version config key.
  4. Commit Creates a conventional commit with the version bump.
  5. Tag Creates an annotated git tag for the new version.
  6. Push Pushes the commit and tag to the remote.
  7. Create GitHub Release Creates a GitHub Release from the changelog, flagging RC builds as prerelease.
  8. Post-release verification Confirms the release is published and the tag is visible.

Inputs

InputSourceDescription
Bump specifierCommand argumentpatch, minor, major, none (RC increment only), or an explicit version.
--prerelease rcCommand argument (optional)Create an RC prerelease version.
--strip-prereleaseCommand argument (optional)Promote an RC to its final release.
--modules mod1,mod2Command argument (optional)Also bump per-module config and manifest entries. Valid: core, lifecycle, dev, creative, testing, all. Implementation note: Currently documented in SKILL.md but not implemented in scripts/version-bump.js. Passing --modules has no effect on the bump.
--dry-runCommand argument (optional)Preview changes without writing.

Outputs

OutputLocationDescription
Version bumppackage.json + configUpdated version number in both locations.
Git tagGitAnnotated tag for the release version.
GitHub ReleaseGitHubPublished release with changelog notes.

Examples

Note: No example demonstrates --modules because the flag is currently a no-op — see Arguments section for context.

1. Explicit manual patch release

> /gaia-release patch --dry-run

Current version: 1.127.1
New version:     1.127.2
Files to update:
  - package.json
  - .gaia/config/project-config.yaml (framework_version)

Dry run complete. No files changed.

> /gaia-release patch

Bumping version to 1.127.2...
Committing: chore(release): bump version to v1.127.2
Tagging: v1.127.2
Pushing to origin/main...
Creating GitHub Release v1.127.2...

Release v1.127.2 published.

2. Minor release with --dry-run preview

> /gaia-release minor --dry-run

Current version: 1.127.2
New version:     1.128.0
Files to update:
  - package.json
  - .gaia/config/project-config.yaml (framework_version)

Dry run complete. No files changed.

> /gaia-release minor

Bumping version to 1.128.0...
Committing: chore(release): bump version to v1.128.0
Tagging: v1.128.0
Pushing to origin/main...
Creating GitHub Release v1.128.0...

Release v1.128.0 published.

3. RC prerelease workflow

Create a release candidate, then increment the RC counter with none.

> /gaia-release minor --prerelease rc

Current version: 1.128.0
New version:     1.129.0-rc.1

Bumping version to 1.129.0-rc.1...
Committing: chore(release): bump version to v1.129.0-rc.1
Tagging: v1.129.0-rc.1
Creating GitHub Release v1.129.0-rc.1 (prerelease)...

Release v1.129.0-rc.1 published (marked prerelease).

> /gaia-release none

Current version: 1.129.0-rc.1
New version:     1.129.0-rc.2

Bumping version to 1.129.0-rc.2...
Tagging: v1.129.0-rc.2
Creating GitHub Release v1.129.0-rc.2 (prerelease)...

Release v1.129.0-rc.2 published (marked prerelease).

4. Hotfix release lane

After a hotfix is developed on a hotfix/{ticket-id} branch targeting main, the release ceremony composes /gaia-deploy and /gaia-release:

# Development (on hotfix/E12-S4 branch targeting main):
> /gaia-dev-story E12-S4
> /gaia-review-all   # full reviews including wire-verification

# Release ceremony (on main after PR merge):
> /gaia-release patch

Current version: 1.128.0
New version:     1.128.1

Bumping version to 1.128.1...
Committing: chore(release): bump version to v1.128.1
Tagging: v1.128.1
Creating GitHub Release v1.128.1...

Release v1.128.1 published.

# Deploy:
> /gaia-deploy --env production
> /gaia-post-deploy

5. Promote an RC to stable with --strip-prerelease

> /gaia-release --strip-prerelease

Current version: 1.129.0-rc.2
New version:     1.129.0

Bumping version to 1.129.0...
Committing: chore(release): bump version to v1.129.0
Tagging: v1.129.0
Pushing to origin/main...
Creating GitHub Release v1.129.0...

Release v1.129.0 published (stable).

What to run next

  • Verify the release on GitHub with gh release view v1.127.2.

Troubleshooting

Not on main branch

Releases can only be cut from main. Merge your sprint PR first.

Working tree is dirty

Commit or stash your changes before releasing.

Version targets disagree

The script detected version drift between package.json and the config. Supply an explicit version to resolve: /gaia-release 1.127.2.