Releasing
full-release.js at the monorepo root versions, tests, publishes, and deploys
the packages that ship together. Tasks isn't one of them: it ships on its own
(see Tasks (peers-core)). Run it from the root. Before any release
mutation or external login check, the script runs the current-tree and history
secret scans, then runs npm whoami against the registry npm publish will use.
It aborts if either scan fails or the npm login is missing or rejected. gh
must be able to see peers-app/peers-services:
npm run release # keep the current version
npm run release -- patch # or minor / major
npm run release runs scripts/release.sh, which injects
~/.config/peers/release.env through op run for that process. 1Password
still asks you to approve the request. The arguments after -- are passed to
full-release.js.
A release takes most of an hour. On macOS the script keeps the Mac from idle-sleeping
until it exits (caffeinate -i): on battery an idle Mac sleeps, the e2e devices' timers stall,
and the gate times out. Closing the lid still sleeps the Mac, so leave it open.
Release credentials
No release step reads a .env file inside a repository. Every credential is
injected into the process environment for the duration of the command by the
1Password CLI
and resolved only when the 1Password app approves the request. The env file
holds op:// references and non-secret identifiers, never values, so it is
safe to leave on disk:
# ~/.config/peers/release.env
PEERS_CORE_SIGNING_KEY="op://<vault>/<peers-core publisher item>/credential"
AWS_ACCESS_KEY_ID="op://<vault>/<peers-release-publisher item>/access key id"
AWS_SECRET_ACCESS_KEY="op://<vault>/<peers-release-publisher item>/secret access key"
APPLE_ID="<apple id email>"
APPLE_TEAM_ID="<team id>"
APPLE_APP_SPECIFIC_PASSWORD="op://<vault>/<notarization item>/password"
| Variable | Used by |
|---|---|
PEERS_CORE_SIGNING_KEY | scripts/publish-peers-core.mjs, which releases Tasks; full-release.js doesn't use it (dedicated item, see Signing key) |
AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY | Step 5 electron-builder publish, and the Tasks S3 upload; the IAM user peers-release-publisher is limited to the peers-electron-app bucket |
APPLE_ID, APPLE_TEAM_ID, APPLE_APP_SPECIFIC_PASSWORD | Step 5 macOS notarization |
The macOS code-signing certificate comes from the login keychain (identity
in peers-electron/electron-builder.js). npm publishing uses the login from
~/.npmrc (npm whoami is checked up front). Windows and Linux installers are
built by the Build and Release workflow in peers-electron from Actions
secrets when Step 3 pushes the tag.
That workflow builds peers-sdk, peers-device, peers-isolate and
peers-cli at the same tag, so a re-run rebuilds the same release. A
re-run also uses the workflow file as it was at that tag. To rebuild a release
with a newer workflow, run it from main with the release's version:
gh workflow run build-and-release.yml -R peers-app/peers-electron -f version=0.30.1
Freezing releases
Create RELEASES_FROZEN.md at the monorepo root and in peers-electron,
peers-sdk, and peers-ui, then disable the Build and Release and
Publish to npm workflows in GitHub (gh workflow disable). full-release.js,
publish-peers-core.mjs, and each repository's release-guard.js (run by the
release:* scripts, prepublishOnly, and the workflows) fail closed while the
marker exists. Lift the freeze with one reviewed commit that removes all four
markers, and re-enable a workflow only after its credentials are confirmed
current. The 2026-10-02 freeze is recorded in
working/done/release-credential-exposure-incident.md.
Install Gitleaks 8.25.0 or newer on the
release machine (brew install gitleaks on macOS). npm run scan:secrets
scans tracked files and non-ignored untracked files in the root and every
initialized submodule. npm run scan:secrets:history scans every repository's
available Git history. CI checks out full submodule histories and runs both.
The committed .gitleaksignore is an incident baseline, not a declaration that
the listed historical credentials are safe. A new entry requires incident
review and a documented reason; never baseline a new current-tree secret merely
to unblock a release. Generated PWA bundles at public/assets/index-*.js are
allowlisted in .gitleaks.toml: they are build output, and generic-api-key
matches minified expressions such as anchor.key. The PWA source is still
scanned. The Electron release workflow independently scans its
archived source tree before any platform build can publish.
Cross-repository Actions access is split by operation. PEERS_REPOS_READ_TOKEN
has only Contents: read on explicitly selected private dependency
repositories; the root secret scan needs that read access across all
submodules. PEERS_SERVICES_WRITE_TOKEN has Contents: read and write on
peers-services only and is used only by the Electron download-link update.
Workflows running in peers-services use their scoped GITHUB_TOKEN for
same-repository pushes. Do not restore the former classic full-control PAT.
Electron packaging uses an explicit application-file allowlist: compiled
bin/, public/, preload.js, package.json, and production
node_modules/. The shared afterPack verifier inspects the ASAR and unpacked
native modules and fails if any other top-level path appears, if forbidden
credential/configuration paths appear anywhere, or if required production
modules cannot load. It also reads packaged application text through the ASAR
Node API and rejects literal SECRET_KEY, rootPrivateKey,
userPrivateKey, or devicePrivateKey values without writing extracted files
into the repository.
Tasks (peers-core)
peers-core is the Tasks app: a sandbox package (declared with /define) that keeps
peers-core's package id. Its npm run build makes the sandbox bundle
(dist/package.bundle.js, which carries the package's manifest), the UI bundle and the
routes bundle.
Tasks ships on its own, apart from the app. full-release.js doesn't version, lint,
build, test, freeze, commit, tag, push, or publish it, and its version doesn't count
toward the app's. peers-core's package.json version is Tasks' own. Step 2b builds it
only as an e2e fixture, because peers-headless installs Tasks from that build.
No app bundles a copy. Electron and the PWA install Tasks from S3, or copy it from
another of the user's contexts (see Where apps get Tasks).
peers-headless still reads the sibling peers-core/dist, so the e2e fleet and
--services-url none hosts install it offline.
Releasing Tasks
scripts/publish-peers-core.mjs runs peers-core's lint and tests, builds it, signs the
three bundles with the peers-core publisher key (see Signing key), and
uploads the tarball and latest-<tag>.json to packages/peers-core/ on S3. The lint and
tests add about three seconds. --version-tag is required, and is beta or stable:
# Beta: what Tasks ships on while it's reworked. Never freezes contracts.
op run --env-file ~/.config/peers/release.env -- node scripts/publish-peers-core.mjs --version-tag beta
# Stable: only when Mark releases Tasks stable. Check the freeze first. This writes nothing,
# but rebuilds dist (add --skip-build to keep it):
node scripts/publish-peers-core.mjs --version-tag stable --dry-run
op run --env-file ~/.config/peers/release.env -- node scripts/publish-peers-core.mjs --version-tag stable
A beta on S3 reaches only the Tasks package rows that follow beta. Every install follows
stable, so a group gets an S3 beta only once its package Info tab follows
stable,beta. During the revamp, Mark's own context gets each beta with
peers packages promote <versionId> beta --group instead (see
Package lifecycle).
A stable release:
- Proves it can publish before it writes anything:
PEERS_CORE_SIGNING_KEYmust be the current publisher key (not revoked), and the AWS credentials must be there. Both come fromop run, so a freeze only happens after Mark approves the 1Password request. A stable release never uses the CLI signing fallback, and refuses--skip-uploadand--skip-build. - Checks that it names what it ships: a committed peers-core checkout; a version newer
than S3's current stable and not tagged
tasks-v<version>, here or onorigin; andpeers-sdkandpeers-uifrom npm, or linked (link-deps.js) to clean checkouts at theirv<version>release tags. A linked checkout'sdistisn't tracked, so build it from that tag. - Runs peers-core's lint and tests, builds, then freezes the contract versions the build
provides:
npx peers-package contract freeze --bundle dist/package.bundle.js, thennpx biome format --write frozen-contracts.json. A freeze can't be undone once it's committed and the release is out. If the build changed a contract version an earlier stable release froze, the freeze fails, nothing is written or published, and the contract needs a new version instead. - Signs and uploads
latest-stable.json. Every new user and every Tasks row that followsstablegets it. If signing or the upload fails after the freeze, the script says thatfrozen-contracts.jsonwas written and nothing was published, and how to undo it (git -C peers-core checkout -- frozen-contracts.json). Running it again instead finishes the release: an uncommittedfrozen-contracts.jsonis allowed, and the freeze has nothing new to add. - Says what's left: commit
frozen-contracts.json, tag the releasetasks-v<version>, push both, and stage thepeers-coresubmodule pointer at the monorepo root.
peers-core's release tags are tasks-v<version>, created by hand after a stable publish.
Its older v<version> tags came from the app releases that used to carry it. Beta
publishes aren't tagged.
Where apps get Tasks
Hosts install Tasks with ensurePeersCore (peers-sdk), into a context that has no
version of it yet:
- A new group copies it from the user's personal context or another of their groups, then falls back to S3.
- A new user's personal context installs the latest stable release from S3 when the app starts.
- Without S3 (an account created offline in the desktop app, or a network that blocks the bucket), nothing installs and Tasks is missing from the Apps screen. A failed S3 check isn't remembered, so the next check tries again: the automatic update check about a minute after the app starts, a new group's install, and each start of the desktop app or load of the PWA. A group created meanwhile gets Tasks from the same update check.
- A dev Electron build installs the same S3 release. To run the local build instead,
use
peers packages reload <peers-core id> -c <context>, as for any package.
Signing key
peers-core is signed by an Ed25519 publisher key. The public half is
peersCorePublishPublicKey in peers-sdk/src/system-ids.ts and ships in every
host; the secret half exists only in a dedicated 1Password item, separate from
the AWS, npm, GitHub, Apple, and Azure release credentials, and is never
written to a file in any repository.
Generate a key pair with the audited script (requires a built
peers-sdk):
node scripts/generate-publisher-key.mjs # prints public key and, once, the secret
node scripts/generate-publisher-key.mjs --public-only
Paste the secret into the 1Password item and keep only the public key.
Publish with the secret injected into the process environment for the duration of the command:
op run --env-file ~/.config/peers/release.env -- node scripts/publish-peers-core.mjs --version-tag beta
publish-peers-core.mjs derives the public key from the secret and aborts
when it does not equal peersCorePublishPublicKey or when it appears in
peersCoreRevokedPublishPublicKeys.
The signed payload includes createdBy. Set PEERS_CORE_CREATED_BY (or
USER_ID) to record a specific peer; otherwise the peers-core package id is
signed. The installer stores that same value, and a client rejects the version
when it does not match the signature. 0.25.12 and 0.25.13 omitted
createdBy; do not add a verifier exception for those historical artifacts.
Publish a newer version with the complete signed payload instead.
Rotate when the key is compromised or on schedule:
- Generate the new pair as above and store the secret in a new 1Password item.
- Set
peersCorePublishPublicKeyto the new public key and append the old one topeersCoreRevokedPublishPublicKeys. Rebuildpeers-sdkand every consumer. - Seed the key registry once
peers-servicesis deployed:npm run seed-subject-key -- --subject <peersCorePackageId> --type package --public-key <old> --status revoked --reason compromised, then the same with--public-key <new> --status active. - Release the desktop and PWA hosts. Each client re-pins to the new key on startup and on its next remote update check.
- Publish
peers-corewith the new key. Hosts that have not updated reject it by design and stay on their currentpeers-core; never dual-sign with the revoked key.
Gates
The script aborts on the first failed gate. Two of those gates exist because unit tests on a single process cannot see them:
| Gate | When | Bypass |
|---|---|---|
Step 2b: peers-headless tests + peers-e2e Tier 0/1 | Before any package is versioned or published | --skip-e2e |
After Step 3 pushes peers-services: GitHub Actions main_peers-services.yml (build, test, Azure) | Before peers-electron is processed | --skip-services-deploy |
Both skip flags are for emergency releases only and print a loud warning. The e2e packages are deliberately not in CI; the Azure workflow is CI, and the release script waits for it so a green local test run cannot ship a client against a server that never deployed.
Step 2b also runs make local in peers-webrtc before the Tier 1 scenarios.
The WebRTC scenario skips itself on machines without a sidecar binary, which
is fine on a laptop and wrong on the release machine, so a failed make local
(missing Go, missing checkout) aborts the release instead of letting the
scenario quietly skip. The same rule applies to the pairing and invites
scenarios, which run the real peers-services (built in Step 2) with an
in-memory Mongo: Step 2b checks peers-services/dist/server.js exists and runs
the scenarios with PEERS_E2E_REQUIRE_SERVICES=1, so a machine that cannot
start Mongo fails the release rather than skipping the only end-to-end
coverage of device pairing and the invite mailbox. The first run on a new
machine downloads the mongod binary (see
E2E testing).
Typical Azure time is about seven minutes. The wait polls gh run list for
the just-pushed commit (20 minute timeout) and treats any conclusion other
than success as a failed release, with one exception. The deploy installs
the just-published @peers-app packages from npm, and a runner can get a 404
for a tarball for a few minutes after it's published. When the failed job's
log shows that, the release waits a minute and reruns the failed job, at
most twice. You need an authenticated gh that can read Actions on
peers-app/peers-services and rerun its workflow.
The deploy builds peers-device, which isn't on npm, from its v<version>
tag, using the version in the pushed peers-services package.json. That's
the same release as the @peers-app packages it installs, so a push to
peers-device main never changes what Services deploys, and a
Services-only push between releases builds the last released peers-device.
The Update Download Links workflow builds it the same way.
Server first when the verifier changes
New signatures, handshakes, and other objects that peers-services must
accept are one-way compatible: a new signer plus an old verifier fails, a
new verifier plus an old signer succeeds (or falls back). The 0.25.0
canonical-JSON signature change shipped a client that peers.app rejected
until a later CI fix deployed the matching server.
Rules of thumb:
- Put the new verifier on
peers-servicesand wait for Azure to finish (full-release.jsdoes this wait) before releasing any client that produces the new bytes. - Keep a legacy verify fallback in
@peers-app/peers-sdkuntil you are sure no pre-change clients remain; do not treat that fallback as permanent. - Do not announce a desktop or npm client until
https://peers.appis running the commit you just pushed.
Desktop update signal
Desktop apps treat the version peers-services reports as the newest release
(see How devices hear about a release).
Each release therefore depends on two things:
full-release.jskeeps thepeers-servicesversion in lockstep withpeers-electron. Do not bumppeers-serviceson its own: desktop apps would treat the new version as a release and check the S3 feed for up to 24 hours. The cost is small, but it is pointless.peers-servicesdeploys before the installers reach S3. Devices see the new version within minutes, retry the feed while it lags, and pick up each platform's installer within about an hour of its upload.
Dependency sync
After every release repo is published, Step 4 pins peers-headless to the
version just published. Step 1 only sees versions already on npm, so this pass
is what moves that consumer forward. Step 1 itself runs update-deps.js and
link-deps.js with --host-only, so official package manifests are left
alone.
peers-headless gets @peers-app/peers-sdk set to the release version. The
script fast-forwards that repo, installs from the registry, then lints,
builds, and tests. It commits and pushes only package.json and
package-lock.json inside the peers-headless repo. Its own version stays
0.1.0. It is not tagged or published.
Step 4b does the same for peers-package-template, which peers packages create clones from
its main branch: @peers-app/peers-sdk and @peers-app/peers-ui become the release version
(peer ranges ^<version>). Commit template source changes locally, on main, before
running the release. Before it publishes anything, the release checks that the template is on
main with a clean working tree and fast-forwards it; Step 4b checks again. After Step 2's
builds, the release checks a copy of the committed files with real ids against this release's
SDK and peers-ui, packed from those builds: installed, linted, built, and tested. A template
that no longer builds or passes its tests stops the release there, before anything is
published. Step 4b repeats that check with both installed from npm, as a new package gets
them, commits the dependency pin in package.json, then pushes main, including any local
template commits. The dependency pin stays unchanged until the checks pass, so a failed or
interrupted check can be retried. If the template changes during validation, retry the release
with its source committed and its tree clean. Pushing it after npm publish means a new package
never asks for an SDK that isn't on npm yet; don't push template changes that need an unreleased
SDK before a release.
If either sync fails, the release stops before the later publish steps. A repeat of the same version skips the commit when those manifests are already pinned.
After npm publish, Step 3 waits for the version to be served before the next repo installs it:
npm must list the version and its tarball must download. npm scans new versions first ("Your
package is being processed and may take a few minutes to become available"), which has taken up
to about 25 minutes, so the wait allows 45. If a release
stops partway through Step 3, run it again without a release type (npm run release): it keeps the
version, skips packages already on npm after tagging and pushing their release commits, and
carries on from the first repo it hadn't finished.
Steps 3 and 4 replace the local @peers-app/* links with registry installs,
because the published builds and the desktop installer must use them. Step 6
runs link-deps.js --host-only after Step 5 to put the links back; a release
that aborts after Step 3 starts relinks on exit too. Without the links, the dev
checkout loads two copies of @peers-app/peers-sdk: the dev app reports no
isolated package runtime, and the Tier 1 e2e scenarios fail. If the relink
fails, the script says so; run node link-deps.js before using the dev app or
running e2e.
If Step 5 fails (notarization refused with HTTP 403 means Apple wants a new
developer agreement signed), everything else is already published, so re-run
only that step. By then the abort has put the links back, and
yarn release:local must not run against them: peers-device's
npm rebuild follows the link into peers-sdk and fails in its esbuild, and
the installer would bundle the links instead of the registry packages. First
put the registry installs back in the repos the Mac build compiles: in each of
peers-isolate, peers-device, peers-ui, peers-cli, and
peers-electron, delete the node_modules/@peers-app/peers-sdk and
node_modules/@peers-app/peers-ui links, then run npm install --force.
Then build with the release secrets loaded, and relink whether it succeeds or
not:
cd peers-electron
op run --env-file ~/.config/peers/release.env -- yarn release:local
cd .. && node link-deps.js --host-only
Without op run, the build has no Apple or AWS credentials, so it can neither
notarize nor publish.
Official packages (official-packages/) are not part of this release. Each
one is versioned, built, and promoted on its own through the package
lifecycle (dev, then Promote to beta or
stable). A host release does not version them or bump their @peers-app/*
pins, with one exception. Electron's release workflow builds isolation-smoke
and isolation-consumer from official-packages main with npm ci. So Step 3
pins those two to the SDK and peers-ui it just published, then pushes
official-packages, just before it pushes peers-electron's tag. The release
checks first that official-packages is on main and that those two fixtures'
package.json and package-lock.json have no local changes.
Step 2b still builds isolation-smoke,
isolation-consumer, and timers so the Tier 1 package and scheduler scenarios
can install them; that build does not commit or publish those packages. It first
builds peers-core the same way, before the peers-headless tests, since headless
hosts install Tasks from that build.
The two isolation fixtures build their guest API 3 declarations with
peers-package build through npm run build, as do the isolate test-artifact
builder and Electron's release workflow. Keep their SDK build dependency and
esbuild installed when preparing a fresh checkout.
After the script
- Check the published npm packages (
npm view <package-name>). - Check the desktop artifacts (electron-builder / S3).
- Confirm
https://peers.appis the just-releasedpeers-services. Running desktop apps start checking for the new version as soon as it is. - Commit the
peers-headlessandpeers-package-templatesubmodule pointers at the monorepo root (git add peers-headless peers-package-template && git commit).