Skip to content
brix.v2.15.0+b120c49

Search documentation

Loading search…

    Documentation menu
    Docs / Deployment and releasesRead Markdown
    On this page

    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:

    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:

    {
      "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, 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:

    ## [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

    #
    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.
    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, 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:

    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:

    {
      "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). 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 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:

    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:

    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.
    2. 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.
    3. 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.
    4. 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:

    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:

    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:

    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.
    2. 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.
    3. 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, workspaces, and CLI commands.