> [Agent navigation index](/llms.txt)

# Publishing project releases

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

By default this workflow publishes Git refs and GitHub Releases without deploying an application.
Opt-in promotion instead defers the GitHub Release until production deployment and health checks succeed. Set it up
before your first release, then inspect the repository, version, and source commit in the command's
confirmation prompt. `--yes` skips that review step, so reserve it for a controlled release pipeline.

## Configure project releases

Work from the standalone project or workspace root. You need a GitHub repository, permission to
dispatch its Actions workflows, and an authenticated `gh` CLI for dispatch and monitoring. Commit
and publish the generated workflow before attempting a release; a local workflow file alone cannot
run on GitHub. Configure the private Brix read key in that repository's Actions secrets, and review
the workflow's publication permissions and your branch protection policy.

Scaffold release ownership before editing configuration by hand:

```sh
brix release init --repository example/product

```

This preserves existing release fields, defaults `steps` to `brix verify`, and creates an enabled
missing changelog. Rerunning it upgrades an unmodified Brix-generated workflow (from any Brix 2.1 or
later generator) to the current template; a customized workflow is refused, never overwritten. The
workflow expects a dedicated read-only `BRIX_SSH_KEY` and does not deploy the project unless
`brix.release.promotion` is configured before initialization.

The generated workflow has three jobs. `prepare` runs `brix ci` and your gates against the
candidate; `verify` installs with the setup action's `install: true`, which stops the Brix SSH agent
after installation, then re-derives the candidate metadata and release notes from the trusted
source; `publish` is the only job with `contents: write`, and it installs and runs no project or
dependency code. Its Git-only publish action repeats the structural checks, pushes atomically, and
creates release records. It needs only `git`, `jq`, and `gh` from the runner image, which
GitHub-hosted Ubuntu runners provide; self-hosted runners must supply them. Third-party actions are
pinned to full commit SHAs with a `# vX.Y.Z` comment; Brix's own actions use the exact Brix release
tag, so allow the private Brix repository's actions for your organization.

Runs share the `repository-release` concurrency group, so releases run one at a time and a running
release is never cancelled. GitHub keeps at most one pending run per group: dispatching another
release while one runs and one waits cancels the waiting run, and its `brix release` monitor reports
`Release cancelled`. Wait for the pending release to start before dispatching another, and re-run a
cancelled release after the current one finishes. Job timeouts are 30 minutes for `prepare`, 15 for `verify`, and 10 for `publish`. The
workflow sets `BRIX_BROWSER_INSTALL_DEPS=1` so browser gates can repair Linux browser dependencies
on the hosted runner.

The generated workflow references Brix's actions at the Brix version that generated it and calls
that version's CLI. After every `brix upgrade`, rerun `brix release init` (it also refreshes
`promote.yml` when promotion is configured) and commit the result before the next release; an
outdated workflow can call release commands the new version no longer provides. Customized
workflows are refused, so port template changes into them yourself.

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

```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
    }
  }
}

```

When a field is omitted from hand-authored configuration, defaults are:

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

The initializer deliberately writes `steps: ["brix verify"]`, so a newly initialized project uses
the complete verification gate rather than the three-command fallback above. Keep that generated
setting unless the project intentionally owns a different release gate.

The root manifest and enabled changelog are included automatically. Every linked package manifest
is also included; do not duplicate it in `assets`. Each linked package has a version policy:
`"lockstep"` adopts the root candidate version, while `"preserve"` keeps its own version. Prefer
explicit objects such as `{ "path": "templates/app", "version": "preserve" }` when linking a
template. Legacy string entries default to `preserve` for private packages and `lockstep` otherwise.

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.

Assets must not be ignored by Git. Generated projects ignore `dist`, so planning with
`"assets": ["package.json", "dist/"]` fails immediately and names the ignoring `.gitignore` rule:
a release commit cannot stage ignored paths. Applications deployed by their own pipeline from the
release tag usually keep the default `["package.json"]` and build in that pipeline. Two cases need
committed build output instead: a library distributed by Git tag that ships `dist/`, and an
application using [promotion](#opt-into-slack-approved-application-promotion), which deploys
declared assets and never rebuilds. Both must stop ignoring the output directory and keep it out of
ordinary commits.

For CI releases, run `brix install` and commit its installation inputs before planning, including
the root `pnpm-lock.yaml`. Preparation updates versions and dependency references first, then
installs the candidate and reconciles that existing lockfile before running your gates. The root
lockfile is included automatically in the audited release bytes, including workspace member
releases; do not add a separate copy to each member's `assets`.

Gates must not change the reconciled lockfile. Unexpected installation changes outside release
metadata and the lockfile stop preparation, even inside configured asset directories. Keep registry
authentication in CI credentials rather than resolution URLs: HTTP URLs containing a username or
password are rejected in release lockfiles. Publication retains the verified dependency bytes
without reinstalling or rebuilding them.

Set `brix.release.repository` in the root manifest to the canonical GitHub `owner/repository`; the
ordinary top-level package `repository` field is not the release authority. 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:

```md
## [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.

`brix release` checks each selected project's changelog before showing the plan, so no workflow is
dispatched when `CHANGELOG.md` is missing, `[Unreleased]` has no entries, or the file contains more
than one `## [Unreleased]` heading.

## Choose a version operation

```sh
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 release includes
the root and its configured `linkedPackages`, applying each linked package's version policy.
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; `workspace:` ranges do not require that closure.

## Execute a release

The recommended path is interactive: let the command display the exact plan, inspect it, then answer
the default-No prompt.

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

For example:

```sh
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, reconciles and installs its dependencies, runs the configured gates against it, derives its release notes, and uploads a read-only handoff artifact retained for one day. Verification re-derives that metadata in a separate read-only job. Publication then pushes the artifact's exact candidate branch and tags atomically without installing, rebuilding, or running repository code. It creates no temporary remote refs.

The dispatched plan records a digest of the selected namespaces' canonical tags rather than every
remote tag, so unrelated tag pushes neither invalidate a pending release nor approach the dispatch
input size limit. A new tag in a released namespace fails verification and names the package. Annotated tags are rejected only when they belong to a selected project's canonical release namespace. Unrelated annotated tags such as `vendor-backup` or `<package-name>@backup` are ignored even though their prefixes resemble release tags.

Publication pushes directly to `https://github.com/<repository>` for the configured
`brix.release.repository`, and the request must match the workflow's repository (compared
case-insensitively) and source commit; checkout `origin` push URLs cannot redirect it.

Ctrl+C stops the local monitor, **not** the remote release. Open the printed workflow URL to inspect
its result before dispatching again. A lost connection after dispatch leaves the remote outcome
unknown; inspect Actions and authoritative branch/tag refs rather than treating it as a failed release.

## Publish a branch preview

When another project needs to test unreleased code, local previews provide an explicit tag-only
alternative to the canonical CI path:

```sh
brix release preview --local --dry-run
brix release preview --local --yes

```

Use a clean non-release branch tracking the same branch on `origin`. Preview publication infers its
destination from `origin` (including a fork) and requires matching fetch and push destinations.
Review that destination in the dry run. Unlike canonical release dispatch, this operation runs all
configured gates **locally**, packages their verified output, and pushes only the immutable
`v<base>-preview.branch-<branch>.<source-sha>` tag. It does not advance a remote branch, dispatch
Actions, create a GitHub Release record, or change the stable/next channels.

Install a preview using the exact repository and tag printed by the command. Preview consumers do
not follow a moving channel. There is no skip-verification option, and publishing requires `--yes`;
do not use a preview to bypass a failing canonical gate.

## Publication and records

Preparation failures leave local and remote refs untouched. Atomic publication cannot partially update the candidate branch and tags. Rerunning a failed publication job succeeds without rewriting refs when every planned tag already identifies the candidate and the release branch still contains it, even after the branch advanced; collisions, partial publication, or a diverged branch fail for inspection. Without promotion, GitHub Release records are created after tags; failed record creation is recoverable from those authoritative tags without rebuilding. Only a root release is marked latest; workspace member records are created with `--latest=false`. With promotion, tags identify candidates, not successful production deployments: no GitHub Release, draft, or prerelease record is created until production deployment **and** its health checks succeed.

Generic generated workflows do not require a consumer `ci.yml`; configured candidate steps are their
gates. Publication pushes with the workflow's `GITHUB_TOKEN`, and GitHub does not start
push-triggered workflows for those events, so a consumer `ci.yml` does not run on the release
commit. Rely on the release workflow's gates and candidate audit for it. 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.

## Opt into Slack-approved application promotion

Promotion supports one root application and stable releases only, not independently selected
workspace applications, previews, rollback, or downgrades. Existing library release behavior is
unchanged. It coordinates project-owned deployment commands; it is not turnkey cloud provisioning.

Configure this policy in the root `package.json` before initializing workflows:

```json
{
  "brix": {
    "release": {
      "repository": "example/product",
      "branch": "main",
      "assets": ["package.json", "dist/"],
      "steps": ["brix verify"],
      "changelog": true,
      "promotion": {
        "controller": "https://promotion.example.com",
        "production": "prod",
        "slack": { "team": "T0123456789", "channel": "C0123456789" },
        "stages": [
          { "name": "test", "from": [], "approvers": [] },
          { "name": "preprod", "from": ["test"], "approvers": ["U0123456789"] },
          { "name": "prod", "from": ["test", "preprod"], "approvers": ["U0987654321"] }
        ],
        "deploy": ["bash scripts/deploy-candidate.sh"],
        "verify": ["bash scripts/verify-candidate.sh"]
      }
    }
  }
}

```

Replace the repository, HTTPS controller origin, and Slack team/channel/user IDs with your own.
The referenced shell scripts are **application-owned files you must implement**, not Brix helpers.
Both command arrays must be nonempty. Commands run via Bash from the immutable candidate worktree
with `BRIX_PROMOTION_STAGE`, `BRIX_PROMOTION_CANDIDATE` (candidate SHA), and
`BRIX_PROMOTION_TAG`. Deploy the already-built declared `release.assets`; never rebuild during
promotion. Because generated projects ignore `dist/`, remove that rule before using the example's
`"dist/"` asset (see [asset rules](#configure-project-releases)). Deployment scripts must exit
nonzero on a bad deployment; verification scripts must poll the destination's health and fail
unless it becomes healthy. Ensure they check the intended candidate, not merely an old healthy
instance.

Before running them, `brix promote deploy` checks that the checkout is the claimed candidate SHA,
that the tag matches the manifest version, and that installation left the worktree clean; commit
installation inputs such as the lockfile so the last check passes. Deploy commands run first, then
verify commands, each with `bash` and the job's environment minus controller and GitHub tokens.

Stages are ordered (two to ten), with production last. `test-run` is reserved for
[test-run values](/docs/environment-loading.md) and cannot be a promotion stage. The first stage is automatic and has empty
`from` and `approvers`. Every later stage requires explicit Slack user IDs and at least one earlier
predecessor. A promotion needs **any one** listed predecessor to have succeeded for the **same
candidate**. Here `prod.from: ["test", "preprod"]` deliberately allows an approved hotfix to skip
preprod; use only `["preprod"]` if that bypass must be prohibited.

For a new release workflow:

```sh
brix release init --repository example/product

```

With promotion preconfigured, this creates both `.github/workflows/release.yml` and
`.github/workflows/promote.yml`. For an existing generated release workflow (from any Brix 2.1 or
later generator), configure promotion, then run:

```sh
brix promote init

```

Migration only accepts an untouched Brix-generated release workflow and refuses custom workflows;
do not overwrite custom delivery logic to force migration. It also refuses when `promote.yml`
already exists; refresh both generated files with `brix release init` instead. Review and commit
both workflows before dispatch.

### Scope credentials to jobs and stages

The generated workflows keep each credential in the narrowest job that needs it:

- `release.yml` `publish`: no environment, installs nothing, holds `GITHUB_TOKEN` with
  `contents: write`.
- `release.yml` `register`: `promotion` environment, installs nothing, holds `BRIX_PROMOTION_TOKEN`.
- `promote.yml` `claim` and `complete`: `promotion` environment, install nothing, hold
  `BRIX_PROMOTION_TOKEN` and `deployments: write`.
- `promote.yml` `deploy`: the claimed stage's environment, installs the candidate, holds
  `BRIX_SSH_KEY` only during installation, the stage's secrets, and `id-token: write`.

Controller-facing jobs run Brix's promote action, which uses only `curl` and `jq` from the runner and
passes the token to `curl` through standard input. They use `environment: { name: promotion, deployment: false }`, and the deploy job uses `environment: { name: ${{ needs.claim.outputs.stage }}, deployment: false }`; `claim` records the GitHub deployment against the candidate SHA instead.

1. Create a `promotion` environment whose deployment branch policy allows only the release branch,
   and store `BRIX_PROMOTION_TOKEN` there rather than as a repository secret.
1. Create one environment per stage name (`test`, `preprod`, `prod`, …) and store that stage's
   deployment secrets and variables in it. Prefer OIDC with a cloud trust policy bound to the
   stage environment's subject claim.
1. Wire every secret or variable your scripts read into the deploy step's `env:` in `promote.yml`.
   GitHub never exports secrets automatically; because the job runs in the claimed stage's
   environment, one expression such as `DEPLOY_TOKEN: ${{ secrets.DEPLOY_TOKEN }}` resolves to each
   stage's value. The generated file contains a commented example.
1. Keep `BRIX_SSH_KEY` as the read-only Brix key. The setup action's `install: true` stops its SSH
   agent once the candidate is installed, so deployment commands cannot use it.

Deployment commands never receive `BRIX_PROMOTION_TOKEN`, `GH_TOKEN`, or `GITHUB_TOKEN`. Required
reviewers and wait timers on a stage environment still apply and delay its deploy job; custom
deployment protection rules are not available with `deployment: false`. The deploy job's default
timeout is 30 minutes.

## Provision and operate the controller

Workflow generation does **not** provision a controller. Before releasing, operate one Node.js 24
process per repository with persistent local disk and an HTTPS reverse proxy at the configured
origin. Run from the installed project's root under your service supervisor:

```sh
brix promote serve --database /var/lib/product-promotion/state.sqlite --port 3000

```

The controller listens on `127.0.0.1` by default so only a reverse proxy on the same host can reach
the plain HTTP backend. Pass `--host <address>` deliberately, for example `--host 0.0.0.0` inside a
container whose port is published only to the proxy.

Provision the directory and restrict access to its database and secrets. SQLite uses WAL; retain
the database and its WAL state across restarts and use a consistent backup strategy. Do not use
network filesystems or ephemeral Lambda storage. Do not run multiple controller processes against
the same repository. Route `/slack`, `/health`, and authenticated `/status`, `/register`, `/claim`,
and `/complete` through the HTTPS proxy; keep the plain HTTP backend private.

Inject these controller secrets through your secret manager, never the manifest:

- `BRIX_PROMOTION_TOKEN`: at least 32 random characters, identical in the controller and the
  Actions `promotion` environment.
- `GH_TOKEN`: a repository-scoped fine-grained token with Contents read/write and Actions
  read/write. GitHub App token issuance and rotation, if used, are external responsibilities.
- `SLACK_BOT_TOKEN`: `chat:write` permission and membership in the configured channel.
- `SLACK_SIGNING_SECRET`: the Slack app's signing secret.

Treat every `BRIX_PROMOTION_TOKEN` holder as a release administrator and trusted health authority.
The token authenticates registration, claims, and completion receipts. The controller additionally
accepts a claim only from the active `.github/workflows/promote.yml` `workflow_dispatch` run on the
release branch whose display title is `Promote <attempt>`, as reported by the GitHub API, and later
completion must come from that same run. Brix does not otherwise attest the release workflow or
health check. A holder can register a policy-matching tag and report
health success for an approved attempt. Restrict it to trusted workflows and operators; do not
expose it to pull requests or untrusted jobs. Slack approval does not independently validate these
health receipts. Protect release branches, tags, workflow edits, and secret access accordingly.

Enable Slack interactivity with `https://promotion.example.com/slack`. The configured user IDs
are the approver whitelist; channel membership alone is not approval authority. Use the shared
token in your operator environment to inspect state:

```sh
brix promote status

```

## Promotion outcomes and recovery

Release CI pushes the verified stable version commit and tag, then registers the candidate for
automatic first-stage deployment. Only the newest registered candidate deploys automatically: if
it fails, older candidates are not queued in its place, and the newest needs an explicit retry. Slack offers subsequent approvals. Notes compare the actual
destination baseline, not just the previous candidate; long previews include links to full notes.
After production deploy and verify succeed, the controller publishes the proper GitHub Release
with the full changelog since the previous production deployment plus GitHub-generated notes.
Skipped candidates' changes are therefore not lost from the production release notes.

Existing production baselines are **not imported automatically**. First adoption requires new
managed deployments or an explicitly planned migration strategy; initial notes show a first
deployment rather than claiming to know what was previously live. With no destination baseline,
generated notes list the commit history pinned to the candidate SHA, including commits before
existing GitHub Releases, up to 5,000 commits followed by a pointer to the full history link. They never let GitHub select an implicit previous release.
`changelog: false` skips reading authored changelog content and uses generated notes only. Otherwise
registration requires the candidate's version section, and the controller re-reads `CHANGELOG.md`
at the immutable candidate SHA when it renders notes; its state never stores changelog content.

Notes up to 100,000 UTF-8 bytes appear inline. Larger notes are preserved in a complete
`release-notes-<candidate-sha>.md` release attachment; the body retains the destination baseline,
comparison link, and an explicit download link instead of silently truncating the changelog.
Only after production succeeds, Brix stages oversized notes on a draft, uploads the attachment,
then publishes the release. This also supports GitHub immutable releases, which lock assets at
publication. Upload or publication failure leaves the post-production draft pending; reconciliation
resumes it without redeploying or creating another release. An interrupted starter
upload is removed and retried; a completed attachment with different bytes is never overwritten.
Publication stays pending until the attachment succeeds. Protect release assets from manual edits.

Each attempt is dispatched at most once, persisted before the request. A definitive GitHub
rejection, any 4xx response other than 409 or 429 (for example a missing `promote.yml` or invalid
input), fails the attempt immediately with that status so it can be fixed and retried. Keep the
generated `run-name: Promote ${{ inputs.attempt }}`: the controller uses it to correlate workflows
before claim and to bind the claim to its run.
Slow queued or installing workflows are not redispatched. Failure or cancellation before claim
marks the attempt failed once GitHub reports completion, just like a claimed runner failure.
If no workflow appears within ten minutes and GitHub can be queried successfully, the attempt
fails and offers an explicit retry; late claims for that attempt are rejected. Provider outages
leave reconciliation pending rather than assuming a deployment is safe to retry.
Any configured approver can retry a failed first stage. Inspect controller state,
Actions logs, and the actual destination before retrying: a deployment may have taken effect before
the runner failed. There is no automatic rollback or cancellation UI. Slack notification duplication
is possible after an ambiguous response, even though deployment claims are durable.

If publication pushed the tag but controller registration failed, rerun the failed `register` job.
It repeats registration with the same candidate and tag; reruns of `publish` accept a release branch
that has advanced from that exact published candidate, without rebuilding or rewriting refs. If the
run can no longer be rerun, a trusted operator can recover registration from the project root:

```sh
brix promote register --tag v1.2.3 --yes

```

Supply `BRIX_PROMOTION_TOKEN` securely. This verifies the lightweight stable tag, release-branch
ancestry, manifest version, repository, and promotion stage graph, the same checks CI registration
applies. It does not rerun release gates or
attest how the tag was built: first confirm the successful publication and candidate in Actions.
Registration is idempotent and starts automatic first-stage deployment only for a new candidate;
it does not repeat an existing deployment or bypass later approvals.

Slack messages are re-rendered only when that candidate's own stages, attempts, or offers change,
and the rendered state is persisted, so controller restarts do not repost every message. Messages
for released candidates, and for candidates older than the one in production, stop tracking later
environment moves; they still update when their own attempts or offers change. Notes are
cached per candidate and baseline; first-deployment notes list at most 5,000 commits before
pointing to the full history link.

### Change the promotion policy

The controller's durable state is bound only to the stage graph: stage names and order, each
stage's `from` predecessors, and `production`. Operational settings can change without touching
the database: approvers, the Slack team and channel, the controller origin, `deploy` and `verify`
commands, and key order. To rotate an approver or change a command:

1. Commit the manifest change to the release branch.
1. Restart `brix promote serve` from a checkout of that commit. New approvals use the new approver
   list immediately; attempts that are already queued keep their earlier approval.
1. Retry any attempt claimed between the commit and the restart. The claim job compares the
   controller's policy with the workflow checkout and fails with
   `controller policy differs from the workflow checkout` until the controller runs the same policy.

Each candidate deploys with the `deploy` and `verify` commands from its own tag, so older registered
candidates keep the commands they were released with. Registration, including recovery of an older
tag, compares only the stage graph.

Changing the stage graph fails closed: the controller refuses to open a database recorded with a
different graph, and there is no migration command. A new database starts without environment
baselines, so it loses the no-downgrade guard and release-note baselines until each stage deploys
again, as on first adoption. Plan a stage change as such an adoption and keep the old database for
audit; do not delete it to get past the error.

> 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](/docs/installation.md), [workspaces](/docs/workspaces.md), and [CLI commands](/docs/cli.md).
