release
Cut a Sideboard version. Default: bump, README/changelog, commit, merge, then push/retarget the `v*` tag so `.github/workflows/release.yml` publishes npm (OIDC) and the signed Mac desktop. No workflow_dispatch. Do not pack Electron in a worktree turn. Use for electron release, desktop release, pnpm release, or “I’ll publish npms.”
- License 许可
- Apache-2.0
- 最近更新
- 2026-11-15
- Stars
- ★ 4
- Forks
- 0
01 前言 Front Matter
- name
- release
- description
- Cut a Sideboard version. Default: bump, README/changelog, commit, merge, then push/retarget the `v*` tag so `.github/workflows/release.yml` publishes npm (OIDC) and the signed Mac desktop. No workflow_dispatch. Do not pack Electron in a worktree turn. Use for electron release, desktop release, pnpm release, or “I’ll publish npms.”
03 SKILL.md 正文
Release
Shared version lives in four package.json files (root, apps/desktop, packages/cli, packages/core).
The Release Action runs when a v* tag is pushed to origin. That is the default path. Do not pack Electron in a worktree turn. A human at a real terminal may still run pnpm release patch mac locally.
Long waits (Actions watch, Fly deploy, optional local pack) use .claude/skills/long-running/SKILL.md (/long-running). Do not ask the human to poll.
What “create a new release” means
These phrases are the same default — do not ask which one they meant:
- create a new release
- create an electron release / desktop release
- I’ll publish npms
Do all of the following:
- Electron — bump, then let
.github/workflows/release.ymlpack/sign/publish the Apple Silicon dmg+zip (electron-updaterlatest-mac.yml) when thev*tag is pushed. - npm — the same tag job publishes
@sideboard-ai/core+@sideboard-ai/clivia OIDC. It skips versions already on npm. Do not runnode scripts/publish-npm.jsfrom the worktree unless they explicitly asked. - README — Desktop download URL for
vX.Y.Z. - Marketing — update
site/(andsite/docs/) when the public story changed (install, Slack, features). Homepage download buttons already point at/releases/latest; still refresh copy/screenshots if this cut warrants it. - Changelog — move
[Unreleased]into## [X.Y.Z] - YYYY-MM-DD. - Commit + push — Release commit, retarget
vX.Y.Z, open or update the thread PR against origin. - Deploy if needed — if this cut changed
site/orapps/relay/, Fly-deploy the relay+site (below). Skip Fly when those trees are untouched.
Merge the PR only when asked. Do not publish npm unless they explicitly said publish npm or full release including npm.
Worktree agents
The Action starts when the v* tag is pushed (or moved) to origin. Do not start a local Mac pack. Do not run foreground pnpm release.
-
Merge
origin/main. -
Land feature work. Write
CHANGELOG.md[Unreleased]for what is shipping. -
Bump versions only (skip if
package.jsonis already the new version):node apps/desktop/scripts/release.js patch mac bump-onlySigning env (
apps/desktop/.env) is not required for this path. -
Point README Desktop download at:
https://sideboard-downloads.t3.tigrisfiles.io/Sideboard-latest-arm64.dmg -
Update
site/if the public story changed. Move[Unreleased]notes into## [X.Y.Z] - YYYY-MM-DD. -
Commit (
Release vX.Y.Z). -
Open or update the thread PR against origin. Merge when asked (or when this turn is a Merge PR / “commit push and merge”).
-
After the Release commit is on
origin/main, retarget the version tag onto that commit. A tag left on an older SHA packs the old tree. Force-push only that version tag — nevermain/master.git fetch origin git tag -a "vX.Y.Z" -m "Sideboard vX.Y.Z" origin/main -f git push origin "refs/tags/vX.Y.Z" --forceThat push is what starts
.github/workflows/release.yml. There is no Run workflow button. -
Watch Actions yourself (
/long-running). Do not ask the human to poll.RUN=$(gh run list --workflow=release.yml --limit 1 --json databaseId,headBranch --jq '.[0].databaseId') node scripts/detached-job.cjs start gha-release -- node scripts/watch-gha-run.cjs "$RUN"Do not
gh run watch. It reprints the full TTY every 3 seconds and stalls the log pane.watch-gha-run.cjspollsgh run viewand prints only when jobs/steps change.present_artifacttype=logartifact_id=gha-releasewithcontent=deltaonly. CI on the same commit title is not a second Release — only the tag workflow publishes. -
On desktop job heap OOM or
SecKeychainUnlock/set-key-partition-list: fixrelease.yml(heap →NODE_OPTIONS; keychain → import-cert step, do not passCSC_LINKinto electron-builder), land that on main, retarget the samevX.Y.Z(do not bump).publish-npm.jsskips versions already on npm. This is not the Apple Developer agreement prompt (that fails at notarization). -
Deploy if needed. When
site/orapps/relay/changed in this cut:node scripts/detached-job.cjs start fly-deploy -- fly deploy --config apps/relay/fly.toml --dockerfile apps/relay/Dockerfile . node scripts/detached-job.cjs wait fly-deployFrom the monorepo root (Docker context is
.).present_artifacttype=logartifact_id=fly-deploywithdelta. Details: docs/system/deploy.md.The Fly app id is
sideboard-slack-relay. Fly cannot rename apps, andfly apps renameis not a command. That id is the Sideboard relay (phone, marketing site, and Slack collaboration), not a Slack-only service. Do not createsideboard-relayor changeappinapps/relay/fly.tomlto a name that does not exist.
Human at a real terminal: pnpm release patch mac is still fine for the Electron half; they still publish npm themselves unless they asked otherwise.
Phone (when they asked for a phone release)
The iOS app is apps/mobile (Expo). A desktop v* tag does not build it. After the release commit is the tree you want in the binary, start one production build and let EAS submit it to App Store Connect. Detach it (/long-running); a cloud build plus submit takes longer than a turn.
node scripts/detached-job.cjs start eas-ios -- bash -lc 'cd apps/mobile && npx eas-cli build --platform ios --profile production --non-interactive --auto-submit --wait'
Run that from the repo root so the job id is visible to wait_for_job. eas.json production auto-increments the iOS build number (appVersionSource: remote) and submits with App Store Connect app 6820766038. Do not start a second build for the same cut. eas whoami must already be matthewklevine.
@cursor/sdk (user-installed)
Sideboard does not pack @cursor/sdk. Users install it with Settings → Agents → Cursor → Install (npm i -g @cursor/sdk) so agents can update it without a new Sideboard build.
stage-cursor-runtime.js copies the runner plus execa / smol-toml from packages/core/package.json (same as stage-sideboard-mcp.js). Do not add @cursor/sdk to the root package or to core production dependencies. See docs/system/conventions.md (Desktop pack in a Sideboard worktree).
Signing/notarization for the local pack reads apps/desktop/.env (CSC_*, APPLE_*). GH_TOKEN comes from that file or gh auth token.
GitHub Actions (release.yml)
There is no Run workflow / workflow_dispatch. The workflow runs only when a v* tag is pushed to origin (mattlevine/sideboard):
on:
push:
tags:
- 'v*'
That is why step 8 retargets vX.Y.Z onto the Release commit on origin/main. A tag that still points at an old SHA will run Actions against that old tree.
Three jobs, all on the same tag push:
| Job | Runner | What it does |
|---|---|---|
release-cli |
ubuntu-latest |
Builds/tests, then publishes @sideboard-ai/core + @sideboard-ai/cli via npm trusted publishing (OIDC). |
release-desktop-mac |
macos-latest |
Import Developer ID into a runner keychain, Vite + stage Node/MCP/Cursor runtime and speech-dictate.app, then electron-builder --mac --publish always without CSC_LINK (GitHub Release + latest-mac.yml). If the ~250MB zip 500s on uploads.github.com (Error saving asset), the same step retries that file (and latest-mac.yml) with gh release upload. Job timeout-minutes: 50 (signed step 45) so a wedged notarize/dmg does not sit for the 6h default. |
publish-downloads |
ubuntu-latest |
After the Mac job, copies those assets to the public Tigris bucket (download.sideboard.cloud) via scripts/publish-tigris.sh. Needs repo secrets TIGRIS_ACCESS_KEY_ID and TIGRIS_SECRET_ACCESS_KEY. Also writes Sideboard-latest-arm64.dmg and removes older versioned objects. New builds check https://download.sideboard.build (generic, first build.publish entry). GitHub Releases stay in build.publish so copies that shipped with the GitHub feed can still update. |
release-cli uses permissions: id-token: write. Do not gate it on if: secrets.NPM_TOKEN — GitHub rejects the secrets context in if (Unrecognized named-value: 'secrets'). Do not set NODE_AUTH_TOKEN or setup-node registry-url on that job; both skip the OIDC exchange. Trusted publisher on npmjs.com: mattlevine/sideboard, workflow file .github/workflows/release.yml, no Environment name. The NPM_TOKEN repo secret is unused for this job.
release-desktop-mac signs/notarizes only when repo secrets MAC_CSC_LINK, MAC_CSC_KEY_PASSWORD, APPLE_ID, APPLE_APP_SPECIFIC_PASSWORD, and APPLE_TEAM_ID are set. The job imports the .p12 into a runner keychain and unsets CSC_LINK before electron-builder (electron-builder#10066: set-key-partition-list uses the p12 password, which macOS 26.6 rejects). If MAC_CSC_LINK is empty, it still packs and uploads with -c.mac.identity=null (unsigned; no auto-update). The job sets NODE_OPTIONS=--max-old-space-size=8192 so electron-vite does not OOM on the hosted runner.
Do not treat a SecKeychainUnlock: The user name or passphrase you entered is not correct failure as an Apple Developer Program agreement problem. Agreement / paid-account lapses fail later in notarization (notarytool / “you must first sign the relevant contracts”). The keychain error is local to the runner and is the #10066 path — keep the import-then-auto-discover workaround until a published electron-builder includes the fix.
CI (ci.yml on PR / main push) only tests. GitHub titles those runs with the commit message, so they look like extra Release jobs — they are not.
To fire Actions on current origin/main without a new local pack (human asked to run the workflow):
git fetch origin
git tag -a "vX.Y.Z" -m "Sideboard vX.Y.Z" -f
git push origin "refs/tags/vX.Y.Z" --force
Use the version in package.json. Force-push only that version tag. Watch Actions → Release.
Pushing .github/workflows/*.yml needs the GitHub workflow OAuth scope (gh auth refresh -s workflow). A token without it is rejected (refusing to allow an OAuth App to create or update workflow).
npm publish (only when asked)
pnpm release patch npm
# or, versions already bumped:
node scripts/publish-npm.js
publish-npm.js --dry-run builds and pretends to publish — useful to verify, not a substitute for the human’s real publish.
Full release including npm (only when asked)
pnpm release # patch, desktop + npm publish
pnpm release minor
Worktree agents push the v* tag and watch Actions. Do not run the combined foreground pnpm release from a chat turn.
Do not
- Treat “create a new release” as docs-only or as “ask whether they also want Electron.”
- Publish npm on the default release phrase.
- Use the worktree nickname as the PR or release title.
- Push to
upstreamor merge locally into the main checkout. - Commit
apps/desktop/.envorapps/desktop/release/. - Force-push
main/master. - Pack Electron locally in a worktree turn, or restart a job because the user asked “status?”.
- Expect Actions → Release to have a Run workflow button. Trigger it by pushing a
v*tag. - Ask the human to poll a long job.
04 同仓库更多 Skills
skill-improver
When a miss will recur — you made it twice, or a person told you the rule — write the lesson into the skill before the turn ends. One sentence, in the same change. Run in the turn, not on a schedule.
release
暂无简介
long-running
暂无简介
worktree-install
Reinstall dependencies in a Sideboard worktree after merge-from-main or a lockfile change. Use when `pnpm install` hangs, several worktrees install at once, or a native build is outside the permitted directory.
review
Merge-readiness review for this repository. Use when reviewing a PR, worktree diff, or Sideboard Review (Approve / Approve with nits / Request changes).
phone-screenshots
Capture Sideboard phone or marketing screenshots from the iOS simulator without the Expo tools button. Use when hiding or restoring that button, retaking site/phone images, or the Expo overlay is in the way.