Publishing project releases

Configure Brix-owned versioning and changelogs, choose a version operation, and hand exact release bytes to verified GitHub Actions publication.

Configure project releases

Scaffold release ownership before editing configuration by hand:

brix release init --repository example/product

This preserves existing release fields, defaults steps to brix verify, creates an enabled missing changelog, and refuses to overwrite an existing workflow. The workflow expects a dedicated read-only BRIX_SSH_KEY, runs brix ci before preparation and publication, and does not deploy the project.

Use brix release only when your application or library wants Brix-owned versioning and Git automation. Configure it under brix.release in package.json:

{
  "brix": {
    "release": {
      "assets": ["package.json", "dist/"],
      "repository": "example/product",
      "linkedPackages": [{ "path": "packages/client", "version": "lockstep" }],
      "branch": "main",
      "steps": ["brix check", "brix test", "brix build"],
      "changelog": true
    }
  }
}

Defaults are:

• assets: ["package.json"]
• repository: required at the root
• linkedPackages: []
• branch: "main"
• steps: brix check, brix test, then brix build
• changelog: true

The root manifest and enabled changelog are included automatically. Every linked package manifest is also included and releases in lockstep with the root; do not duplicate it in assets.

List generated artifacts such as dist/ only when they belong in the release commit. Keep those artifacts out of ordinary source commits; configured steps generate them against the candidate version. Steps may write declared assets, but must not commit, move HEAD, or use mutating formatter/linter fixes.

Set root repository to the canonical GitHub owner/repository. Releases reject same-named repositories on another origin. This identity is project configuration; generic Brix projects are not hardcoded to the Brix framework repository.

Maintain the changelog

When changelog handling is enabled, add user-visible changes under:

## [Unreleased]

- Added release automation.

Do not write the version heading yourself. The release command renames [Unreleased], adds the date, and creates the next empty section. Set changelog: false for an application that intentionally does not maintain one.

Choose a version operation

brix release patch
brix release minor
brix release major
brix release next major
brix release next
brix release stable
brix release patch --project packages/core --project packages/ui

patch, minor, and major select stable SemVer changes. From a stable version, next patch|minor|major starts that prerelease line at next.1; plain next advances an existing prerelease or starts the next patch line. stable promotes 2.0.0-next.N to 2.0.0; patch promotion remains supported. Starting a different prerelease line from a prerelease, promoting a stable version, reusing a candidate, or reopening a closed line is rejected.

The CI release path does not support preview releases. Without --project, the root and its configured linkedPackages release in lockstep. Repeated --project <selector> options select independently versioned workspace members and apply one shared bump. Their lightweight tags are namespaced <package-name>@<version>; the root tag is v<version>. Select any otherwise-unselected member that has an exact dependency on a selected package.

Execute a release

1. Record the change under [Unreleased] when enabled.
2. Commit all source work and confirm the tree is clean.
3. Update a stale checkout yourself; Brix never pulls or rebases.
4. Run the chosen operation and review the displayed repository, branch, source commit, projects, version changes, and tags.
5. Confirm the prompt, which defaults to No, to dispatch. Declining does not dispatch.

For example:

brix release patch
# Review the plan, then answer the confirmation prompt.

For automation, use brix release patch --yes or its -y alias to bypass the prompt. A noninteractive invocation without either flag fails rather than dispatching. The command queries live remote branch and tag refs but does not fetch, run steps, write, commit, tag, or push locally. A release requires the configured branch to track the same branch on origin, with local HEAD equal to its live remote SHA. Canonical stable and next.N tags are the version authority and must be lightweight.

After confirmation, the local command dispatches the displayed plan, still bound to the exact source, to GitHub release.yml and waits with gh. It runs no local gates and makes no local release mutations. CI prepares the candidate in a temporary worktree, runs the configured gates against it, and uploads a read-only handoff artifact retained for one day. Publication validates candidate metadata and atomically pushes the artifact's exact candidate branch and tags without rebuilding. It creates no temporary remote refs.

Publication and records

Preparation failures leave local and remote refs untouched. Atomic publication cannot partially update the candidate branch and tags. GitHub Release records are created after tags; failed record creation is recoverable from those authoritative tags without rebuilding.

Generic generated workflows do not require a consumer ci.yml; configured candidate steps are their gates. The Brix framework repository adds its own exact-SHA CI prerequisite. scripts/bootstrap-source.sh is required only by the Brix framework source repository.

Never delete a shared remote tag, rewrite release history, or guess a new version to hide a collision.

This guide is for consumer applications and libraries. The private Brix framework applies additional repository-maintainer checks and binds its canonical repository through its own configuration.

See installation, workspaces, and CLI commands.