apps/cli/package.json owns the product version. scripts/releases/config.ts
derives the npm channel, native targets, Docker tags, desktop identity and
installer names. Build scripts and the website consume that configuration.
Source workspaces remain private; only staged runtime packages are published.
Use the pinned Node and Bun versions in .github/actions/setup/action.yml.
bun run release:cli
bun run release:wrapper
bun run release:desktopOutside CI, release:cli first removes the workspace's .local/releases builds for the same
platform at other versions (scripts/releases/prune-builds.ts), keeping any that a running
process has open. release:cli and release:desktop do not start below the free-space floor
described in e2e/README.md (EXECUTOR_DISK_FLOOR_GB, 20 GB by default).
These commands never publish. macOS public installers require
bun run release:desktop --notarize, with the five EXECUTOR_MAC_* credentials
from the Agents vault. The signing helper owns a temporary keychain and an
in-memory notary key file and removes them after the build.
The Executor releases workflow (release-artifacts.yml) defaults to
build. It reads the committed version, builds all five native platforms,
tests installed CLI archives and desktop restart behavior, checks OS credential
setup and key-loss refusal, and runs the native Docker scenarios on amd64 and
arm64. It also produces the checksum-pinned Git companion source archive.
Every job runs on Blacksmith. macOS builds use Apple Silicon runners; the Intel
job uses x64 Node and Bun under Rosetta and tests the x64 runtime and desktop.
Both macOS targets run on the 6-vCPU Mac runner (scripts/releases/config.ts).
The pinned Bun installer patch keeps its selected binary architecture under
Rosetta, matching the optional dependencies installed by the package manager.
Windows installers are currently unsigned.
Each run also builds the Rust telemetry collector (packages/telemetry/collector) once per
target in its collector (<target>) job, on that target's local runner. Every job that packages
the CLI runtime (local, checks, cli and the recovery parts) starts with the run, waits for
its own target's collector job at "Wait for the telemetry collector"
(scripts/releases/collector-job.ts), and downloads that one build as the collector-<target>
artifact, so the archives the archives job compares hold the same bytes. A collector job that
fails or is cancelled stops its target's packaging jobs at once, and releases names it. Runs
that publish build the collector without restoring from the cache, because an entry in main's
cache scope is not proof of what built it; the cache rules judge restores by workflow file, so the
paced check and build runs build it too (.github/actions/collector). A narrowed build runs a
collector job only for the targets its packaging jobs run on, and none when it runs only the image.
Every packaging job packages the collector it fetched, executable before anything is signed, and
builds the viewer the CLI and desktop serve from it; the image builds its own collector in its
Dockerfile's collector stage.
A Bun runtime release built from a pull request's branch, as one that changes the
lockdown patch needs, is the one main's publishing runs use from then on. If that
branch's scripts/releases/bun-runtime/ changed after the build and before merge,
delete the release before merging so main builds it again; see
the release scripts.
Executor 2 desktop installs update from their own channel feed. The channel is
fixed at build time from the version: 2.0.0-beta.N builds follow beta and
stable builds follow latest. There is no in-app channel switch. Install a stable
build to leave beta.
Executor 1 reads GitHub's release list in the same public repository, so v2
never uses the GitHub provider or electron-updater's default latest*.yml
names. scripts/releases/config.ts defines a generic feed in the published
prerelease executor-v2-desktop-updates:
| Platform | Beta file | Stable file |
|---|---|---|
| macOS | executor-v2-beta-mac.yml |
executor-v2-latest-mac.yml |
| Windows | executor-v2-beta.yml |
executor-v2-latest.yml |
| Linux x64 | executor-v2-beta-linux.yml |
executor-v2-latest-linux.yml |
| Linux arm64 | executor-v2-beta-linux-arm64.yml |
executor-v2-latest-linux-arm64.yml |
Each file lists absolute URLs to the versioned release assets and their blockmaps. The feed release never becomes GitHub's latest release, so v1 installs never see it. Its first publication creates it on the release's public commit.
The desktop build writes app-update.yml for Windows, Linux and signed macOS
builds. Unsigned macOS review builds have no feed because Squirrel.Mac only
installs signed updates. Linux checks only inside the AppImage; .deb installs
update from the download page.
Publishing updates the channel last, after the versioned release is public.
scripts/releases/desktop-feed.ts checks every platform's metadata against the
installer bytes, merges the macOS arm64 and x64 entries, and writes the files.
A stable release writes latest and moves beta forward unless beta already
holds a newer version. Rerunning the upload replaces the same files. To roll a
channel back, publish a newer fixed version; installs never downgrade.
The app checks 15 seconds after launch and every four hours, downloads quietly, then offers Restart or Later once per version. Updates → Check for updates… checks at once and offers a version declined earlier. The backend stops before installation. Updates never install on quit.
New apps pin the apps version in packages/apps/package.json, so every host
must ship a version that npm holds with exactly the content this checkout
builds. Every change to the framework, including the workspace libraries
bundled into it, bumps that version in its PR (and the host protocol when the
host boundary changes). Merging allocates the numbers and the deploy from
main publishes them. Never publish apps from a branch or by hand; see
publishing apps.
scripts/releases/apps-published.ts runs after bun run apps:build. It packs
the staged package and compares every file with the published archive of the
same version:
- The deploy workflow's
appsjob runs it with--publishin thereleaseenvironment before the production deploy job. An unpublished version is published with--tag beta; a published one is only compared. - Publishing runs of Executor releases run it without a flag, so the version must already be on npm unchanged.
- Pull request checks run it with
--allow-unpublished: an unpublished bump only warns, while a published version with different content fails.
Pull requests also run scripts/releases/apps-bumped.ts, which builds the base
commit's package and fails when the staged package changed but the version did
not.
The Beta workflow (.github/workflows/beta.yml) publishes betas. It checks
on every push to main, when CI passes on a push to main, and on a schedule
at minutes 8 and 38, and
scripts/releases/beta-due.ts decides from npm, the release runs and main's
history. Before deciding, each tick runs scripts/releases/lock-repair.sh, which
pushes Refresh bun.lock [skip ci] when main's bun.lock is not what
bun install writes and the only difference is workspace packages' own versions.
Any other difference is only reported: a warning in the run summary and one open
issue labelled lock-repair-refused (scripts/releases/lock-repair-issue.sh),
which a later tick closes when it finds the lock fresh. The repair never holds a
beta. That commit follows the merge that left the lock stale, so it
never makes a beta due by itself, and its [skip ci] starts no Executor releases
run. A push and a scheduled tick decide alike:
- While any build or publication of Executor releases is queued or running, it waits. A check, which publishes nothing, does not hold it.
- It starts no beta and no further attempt while the release matrix on
mainis red. The matrix runs are the checks, the Executor releases runs that the Release check workflow starts with a repository dispatch after main changed what a release lane builds or runs, paced to one build every two hours, and the runs titled(build), dispatched frommainby hand. Checks list apart from builds and publications, so they never crowd the publishing attempts out of what the decision reads. The newest finished one must have passed itsreleasesjob. A run that tested nothing is skipped: a cancelled one, and a check whosepacejob did not pass or whose matrix did not run. A push that changed nothing a release lane reads starts no check, so it neither holds a beta nor lets one through. A failed run holds every beta, with a warning, until a later run passes. To clear a hold once the cause is fixed, merge the fix, or rungh workflow run release-artifacts.yml --ref main -f channel=build. A run still pacing or building holds nothing, since the publishing run tests every platform on the commit it publishes and publishes only when all pass. - Release check also starts the installed CLI suite on Windows, a narrowed
build (
jobs=cli,targets=win32-x64, about USD 1.40 and 13 minutes), on a decision of its own (e2e/release-check.ts,windows): it compares main with the last commit a Windows check tested, or will, never with the Linux check's, so a commit the Linux check already covers still gets its Windows run. It starts at most once every four hours; a decision inside that wait skips it and keeps the comparison where it was, so the first push or hourly backstop after the four hours starts it for every commit since. A decision that fails starts it. It runs from theci/windows-checkbranch, which the step sets to main's commit, so it never shares a concurrency group with a publication frommain, and Beta neither waits for it nor counts it. A red one shows a Windows-only failure hours before a publishing run would; the red-main issue reports it. - A build run can be narrowed, to prove one job on one platform without paying
for the whole matrix (a full build costs about USD 7; the installed CLI suite
on Windows alone about USD 1.40):
gh workflow run release-artifacts.yml --ref <branch> -f channel=build -f targets=win32-x64 -f jobs=cli.targetstakeslinux-x64,linux-arm64,darwin-x64,darwin-arm64andwin32-x64;jobstakeslocal,checks,cli,recoveryanddocker; both are comma-separated, and empty means all. Itsreleasesjob requires only what it ran, andarchiveschecks the parts it ran but skips the comparison of tested and published archives, which needs every packaging job. It is titled(build, <jobs> on <targets>), so Beta and the red-matrix issue, which read a(build)run as the whole matrix, never count it; wait for it with that title (ci-wait --workflow "Executor releases (build, cli on win32-x64)" --dispatched). Checks, publications and notarizing builds always run everything, and refuse to be narrowed. - When npm lists the committed version, main has commits after that version's
Release 2.0.0-beta.Ncommit, and npm published it at least six hours ago, it commitsRelease 2.0.0-beta.N+1tomainand dispatches Executor releases with channel beta. - When npm lacks the committed version, it publishes it again instead of
skipping it. At most five publishing attempts a day fail: once five failed in
the last 24 hours, counting each re-run of a run as an attempt of its own, no
tick starts or re-runs another, a manual dispatch of Beta
included, until one of them is a day old (dispatch Executor releases with
channel beta by hand to publish sooner, after inspecting them). It finds
them by when they ran: the release runs of the last month (GitHub re-runs a
run only within 30 days), and the earlier attempts of those re-run in the last
day, stopping once five are known. When ten requests cannot tell, the tick
holds. Within that
bound, an attempt that failed before publishing is dispatched again on the next
tick. After two failures in a row, the next attempt waits six hours after the
last one and for a new commit on
main, or a day, unless CI has passed on amaincommit after the last attempt's: a failure that a merge fixed is retried as soon asmainis green again. Beta also ticks when CI finishes green on a push tomain, so that retry starts within minutes. - An attempt that failed in a step that publishes anything is never retried that
way: it has its failed jobs re-run once from its own artifacts; after that,
inspect it as below. It is judged by the step, not the job's name: every step
of
release-artifacts.ymlandbun-runtime.ymldeclares in itsenvwhether it publishes,PUBLISHES: "yes"(every step of thepublishjob, the docker job's architecture push, the dispatch of Deploy and the Bun runtime's release) orPUBLISHES: "no", ande2e/tests/beta-due.spec.tsfails a step that declares neither, so give every new step one. A run's job is found by the job id at the start of its name, which GitHub cuts short for a long matrix job; a job or step that cannot be found counts as publishing (scripts/releases/publishing-steps.ts). Each skipped retry leaves a warning on the Beta run, and the failed release runs stay red. - Only publishing runs count as attempts. A dispatch with channel build does not publish, so it neither adds to a failure streak nor counts as a success, though it still makes the tick wait while it runs.
- When the last publishing run for the committed version (its commit contains
the
Releasecommit) succeeded but npm still lacks the version, every tick fails red instead of dispatching again: another run would succeed the same way without publishing. Inspect that run's publish job and the registry, fix the cause, then dispatch Executor releases with channel beta by hand.
GitHub delivers this repository's schedules hours late and drops the ticks in
between: in the 30 days to 2026-11-11 a */5 cron ran about five times a day and
an hourly one about four and a half. So merges drive publishing, and the schedule
is a backstop. Without merges, a beta that waits out the six hours, or a retry
after a failed attempt, waits for the next merge or the next scheduled run, which
has come up to 11 hours apart.
Ticks never overlap. While one runs, one more waits; a newer tick replaces the waiting one, and it reads main afresh, so a burst of merges costs a few runs. When a merge lands between a tick's checkout and its bump push, the push is refused; the tick pushes nothing and passes with a notice, because that merge started a tick of its own, which decides again. A refusal while main has not moved fails the tick.
Dispatching Beta by hand publishes new commits at once, skipping the six
hours and the retry back-off. A merge that lands while a manual dispatch
waits behind a running tick replaces it; dispatch it again. The bump commit is pushed over SSH with the
deploy key in the beta environment's BETA_PUSH_KEY secret, the one actor
the main ruleset lets push without a pull request (see
CI configuration). Its message ends in [skip ci], so it starts
no CI, Deploy, public export, Cloud tests or Beta run; the next merge carries it.
To publish a beta by hand instead, set the version to an unused
2.0.0-beta.N, merge the reviewed release changes, and dispatch Executor
releases from main with channel beta. The workflow refuses a channel
that does not match the committed version.
- Build and test every native runtime, desktop installer and Docker architecture.
- Export the filtered source snapshot to the public repository's
v2-releasesbranch. Createexecutor@<version>on that public commit, never a private SHA. - Upload installers, native archives, the npm launcher, bundled Git source and SHA256SUMS to the draft.
- Publish the tested Docker manifest as
:<version>and:beta, then make the GitHub prerelease public withlatest=false. - Publish the npm launcher, which downloads the native archives from that public release. It records each archive's SHA-256; publication checks them against the build and the release's SHA256SUMS, then polls the registry archive and compares its integrity.
- Verify a clean
executor@<version>installation from npm, including its first download. - Point the Homebrew formula and the desktop
betaupdate channel at the public release assets.
The npm latest tag, Docker latest, and Executor 1 desktop updater stay
unchanged. A draft public release blocks accidental repeat publication of the
same version. After a partial failure, re-run the failed publish job. It resumes
only its own release, whose target is this source's unchanged public snapshot:
a draft gets its assets again, and a release already public keeps them, which
npm publication then checks. It skips an npm launcher whose registry integrity
matches the local archive. Any other
existing release or npm version stops publication for inspection. Never
republish an accepted immutable npm version merely because its registry entry is
still propagating.
No publish step moves a channel backwards. The job's first step after setup
reads every channel (npm's tag, the image's channel tag, the published formula,
the desktop feed) and refuses a release older than any of them, and each step
that moves a channel checks its own again just before it moves it
(scripts/releases/channel-guard.ts). After a failure the job summary says what
the release made public and what it did not, read from the public surfaces, and
whether re-running the failed jobs would finish it
(scripts/releases/publication-report.ts).
A re-run uses the workflow file of the run's own commit, so runs started before
those checks were added carry none. Never re-run the publish job of an older
release once a newer one exists: beta.51's run (43640118286) and beta.52's,
re-run after a newer beta, would point the image's beta tag back at it.
The homepage resolves desktop downloads in the browser from GitHub's public
release list, choosing the newest published release with this major version's
tag prefix. A merged version bump keeps linking to the previous release until
this one is public; without JavaScript, or when the lookup fails, the buttons
open the releases page. The documentation's install commands name the newest
release npm's dist-tags list, read when the site builds (scripts/releases/published.ts),
so they too keep the previous version until publication moves the tag and the
next deploy from main rebuilds the site. Verify the public npm install, GitHub
assets, Docker manifest and rendered site.
A successful upload alone does not establish public availability.
Get explicit approval for the v2 stable release. Change the version to 2.0.0
and dispatch the same workflow with latest. npm already serves executor@2.0.0:
it was published on 2026-03-16 from a stale historical tag and is deprecated.
npm never accepts a version twice, so a release numbered 2.0.0 cannot be
published, and the publish job's preflight refuses it before anything moves. The
first stable release needs a number above the betas that npm does not hold; the
choice is the owner's. The version, tags, filenames
and links change together. The fixed desktop identity com.usefulsoftware.executor.v2,
product name Executor 2, profile Executor v2, and CLI data directory
~/.executor/v2/cli remain unchanged. Stable publication writes the desktop
latest channel and moves beta installs forward. Marking v2 as GitHub's latest
release also changes what Executor 1's updater reads; decide v1's path before cutover.
Changesets still orchestrates separately published workspace packages. The product archive includes private workspace packages and uses the CLI manifest as its single release version; the removed v1 release script is not a second publishing route.
apps/hosted/cloud/alchemy.releases.ts owns the eight required secrets in the existing release
environment. It is separate from the unapplied broad CI stack, so
applying releases does not change production credentials, repository policy or
Cloudflare deployment tokens. Missing credentials fail the apply.
From the cloud package, use alchemy deploy alchemy.releases.ts --stage ci --dry-run --no-input to review, then --no-input --yes to apply. Resolve an
ignored Agents reference file through agent-vault run --env-file.
The environment is created once by a repository administrator with a bare
PUT /repos/UsefulSoftwareCo/executor-next/environments/release. It already exists.
Secret providers require it to exist and never change its protection rules.
The IaC token needs Environments read/write and Metadata read on
UsefulSoftwareCo/executor-next. GitHub cannot restrict it to one environment.
Public releases use a GitHub App installed on UsefulSoftwareCo/executor with
Contents read/write. Its installation tokens have their own rate limit, so a
release cannot fail because a person's token is busy elsewhere.
The release stack requires NPM_TOKEN, PUBLIC_RELEASE_APP_CLIENT_ID,
PUBLIC_RELEASE_APP_PRIVATE_KEY,
EXECUTOR_MAC_SIGNING_KEY, EXECUTOR_MAC_SIGNING_CERTIFICATE,
EXECUTOR_MAC_NOTARY_KEY, EXECUTOR_MAC_NOTARY_KEY_ID, and
EXECUTOR_MAC_NOTARY_ISSUER, plus GitHub and Cloudflare state credentials.
Normal main pushes continue exporting to public v2 through
scripts/export-public.sh. Release snapshots use v2-releases so a release
cannot race or replace a newer main export. Both use
scripts/export-public.exclude; private history and internal notes stay private.
A main export also merges the public pull requests that main ports, named by
Public-PR lines in its commit messages; a release export merges none, because
no pull request targets v2-releases.
Each public release's notes list what changed since the release before it, then
the install instructions at the top of
the release scripts' README. The metadata job of a
publishing run writes them with scripts/releases/release-notes.ts, before any
build, and the publish job creates the release with them. They are not GitHub's
generated changelog, which would list private pull requests and their titles.
The notes list only changes whose squashed commit on main has a line
Release-note: <text>, and that text is all they say about the change. Pull
request titles stay private: the notes never print one, nor does any warning
the script writes. Release-note: none is the same as no line.
A line counts only when Release-note: starts a line of the message's body:
not indented, not quoted with > (as a revert may quote the message it
reverts) and not inline. A commit message that holds <, [, $, ``` or
~~~ anywhere, title included, has no notes at all, because HTML, a link
definition, math or a code fence can hide a line from whoever reads the message
rendered; the job log warns with the commit and the character. The one
exception is a line that is a co-author trailer and nothing else, anywhere in
the message, since a squash joins its commits' messages and a port's own
trailers sit in the middle: Co-authored-by: <name> <address> (the key in any
case), then only spaces, where the name holds no <, >, [, ], $,
backtick or control character but may end [bot], and the address, the line's
only <...>, is <local@host> with a local part of letters, digits and
._+- (a bot's ending [bot]) and a host of letters, digits, dots and hyphens.
Any other < or [, even on a line that only starts like a trailer, still
drops the notes. So write an
example note in words, not in a code block or comment. Any other line that
holds Release-note: is not counted, and the job log warns with its commit and
line number. When a change has several lines that count, each is listed, once,
in the order written; none among them is skipped. A line cannot be withdrawn
by a later one, so reword or drop the commit before merging instead.
A note may start with the kind of change it is: Feature: , Improvement:
or Fix: (the word in any case, then a colon and exactly one space, not a
tab or two spaces, which leave the note refused), as in
Release-note: Improvement: Search answers faster. The kind is not part of the
note: it is cut off first, and the rules below apply to the text after it,
which must itself start with a letter or a digit and is counted against the
300 characters without the kind. It is never published, in the release, the
desktop feed, Cloud's notes or anywhere else. A note without one is a fix. A
kind with no note after it, or with none, is refused. Cloud's What's new
leads with the newest feature or improvement of its notes, never a fix; with
neither it shows a plain line, and its panel lists every note, fixes included,
in order. So write Feature: for something new and Improvement: for
something that already worked and now works better, and Fix: or nothing
for something that was broken. Mark a note for what it is, and never reword a
fix to sound like a feature. --check prints the kind it counted for each
line. scripts/releases/note-kinds.ts gives one note merged before kinds
could be written its kind by hand, since a commit message on main cannot change;
it is a stopgap, so never add to it, and delete it once that commit leaves
Cloud's 30 days (the file says when).
A note is published only when it is plain prose, and then exactly as written.
It may hold only ASCII letters, digits, spaces and these punctuation marks:
. , ; : ! ? ' " ( ) -. It must also:
- start with a letter or a digit, and not like a numbered list (
1.,1)); - have a colon only before a space or at its end, so no
:emoji:orscheme:; - have a dot only at the end of a sentence or between digits (
1.5), never inside a word as in a host name (example.com,www.x); - join no letters to digits with a hyphen (
GH-123,ABC-123); - hold no whole word of 7 or more hex characters or digits, which GitHub links
when it names a commit (so
deadbeef,defacedand1234567are refused, and a number is written1,000,000); a word that only holds such a run, such asfeedback, is fine, because GitHub links a commit only as a whole word; - name no
GHSA-advisory and no private repository; - be at most 300 characters.
So a note holds no @, #, /, <, >, [, ], &, *, _, ~, |,
backslash, backtick, typographic quote or dash, accented or non-Latin letter,
emoji or invisible character: no mention, issue or pull request reference,
owner/repo, URL, email address, code, HTML or Markdown. Write a command or a
name in words. Any other note is left out whole, never rewritten or cut, and
the job log warns with its commit, its line number and the first rule it
breaks. All listed lines together hold at most 10,000 characters: once a
change's lines would pass that, it and every later change are left out and
counted, with a warning. Neither stops the release, because a commit message on
main cannot be changed.
e2e/tests/release-notes-render.spec.ts (CI's tooling job, with the job's
token) sends a corpus of accepted notes, as the script writes them, to GitHub's
Markdown API and checks that each comes back as its text alone, inside nothing
but the notes' headings, list and paragraph. It also renders the refused corpus
and checks that the forms review found active still render as links, mentions,
an emoji image or markup. The corpora are in e2e/release-notes-repositories.ts.
A change with a line is listed when it changed a package the CLI, the desktop
app or the self-host image is built from, other than its scripts, tests,
fixtures and Markdown, under All installs, CLI and desktop, or Self-host by the
packages it changed. A line on a change to nothing a release ships, such as
Cloud-only code, CI or tooling, is not listed, and the job log warns with the
commit. A port of a public pull request with a line links it and thanks its
contributors by GitHub handle. That credit is the one place the notes hold a
link and a mention, and it is safe because it is built only from a Public-PR:
line that names UsefulSoftwareCo/executor#<number> exactly and from handles
in users.noreply.github.com co-author addresses that match GitHub's handle
rule, never from free text, so it can only point at a public pull request and
the people who wrote it. Anything else gets no credit and a warning in the job
log, and the note is listed as if the change were no port. A revert and the change it reverts cancel when
both are in the release, newest first, so a reverted revert cancels nothing and
the change it restored is listed. Every change not listed is counted in one
line. A release with no line at all says "No release notes were written for
this release." and still publishes. The notes link nothing else: no compare
view, commit or private pull request.
Warnings go to the publishing run's job log and its annotations in this
private repository, and name commits only, never a title or a note's text. The
notes themselves reach the public repository only as the release's body: the
release-notes artifact is downloaded outside .local/publish, so it is never
uploaded as a release asset.
Write the line for a change a user of the CLI, the desktop app or the self-host
image would notice: one plain sentence saying what changed for them, in the
words above. Name no
customer, organization or reporter, use no internal names, and say nothing about
a security problem not yet fixed and disclosed. Put it in the body of a commit
message on the pull request's branch, not only in the pull request's
description: this repository squashes with the commits' messages as the body
(squash_merge_commit_message: COMMIT_MESSAGES), so the description never
reaches main.
To see a release's notes without publishing, run
node scripts/releases/release-notes.ts --version <version> --to <its Release commit>
from a checkout of main.