AGENT SKILL

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:

  1. Electron — bump, then let .github/workflows/release.yml pack/sign/publish the Apple Silicon dmg+zip (electron-updater latest-mac.yml) when the v* tag is pushed.
  2. npm — the same tag job publishes @sideboard-ai/core + @sideboard-ai/cli via OIDC. It skips versions already on npm. Do not run node scripts/publish-npm.js from the worktree unless they explicitly asked.
  3. README — Desktop download URL for vX.Y.Z.
  4. Marketing — update site/ (and site/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.
  5. Changelog — move [Unreleased] into ## [X.Y.Z] - YYYY-MM-DD.
  6. Commit + push — Release commit, retarget vX.Y.Z, open or update the thread PR against origin.
  7. Deploy if needed — if this cut changed site/ or apps/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.

  1. Merge origin/main.

  2. Land feature work. Write CHANGELOG.md [Unreleased] for what is shipping.

  3. Bump versions only (skip if package.json is already the new version):

    node apps/desktop/scripts/release.js patch mac bump-only
    

    Signing env (apps/desktop/.env) is not required for this path.

  4. Point README Desktop download at:

    https://sideboard-downloads.t3.tigrisfiles.io/Sideboard-latest-arm64.dmg

  5. Update site/ if the public story changed. Move [Unreleased] notes into ## [X.Y.Z] - YYYY-MM-DD.

  6. Commit (Release vX.Y.Z).

  7. Open or update the thread PR against origin. Merge when asked (or when this turn is a Merge PR / “commit push and merge”).

  8. 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 — never main / 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" --force
    

    That push is what starts .github/workflows/release.yml. There is no Run workflow button.

  9. 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.cjs polls gh run view and prints only when jobs/steps change.

    present_artifact type=log artifact_id=gha-release with content=delta only. CI on the same commit title is not a second Release — only the tag workflow publishes.

  10. On desktop job heap OOM or SecKeychainUnlock / set-key-partition-list: fix release.yml (heap → NODE_OPTIONS; keychain → import-cert step, do not pass CSC_LINK into electron-builder), land that on main, retarget the same vX.Y.Z (do not bump). publish-npm.js skips versions already on npm. This is not the Apple Developer agreement prompt (that fails at notarization).

  11. Deploy if needed. When site/ or apps/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-deploy
    

    From the monorepo root (Docker context is .). present_artifact type=log artifact_id=fly-deploy with delta. Details: docs/system/deploy.md.

    The Fly app id is sideboard-slack-relay. Fly cannot rename apps, and fly apps rename is not a command. That id is the Sideboard relay (phone, marketing site, and Slack collaboration), not a Slack-only service. Do not create sideboard-relay or change app in apps/relay/fly.toml to 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 upstream or merge locally into the main checkout.
  • Commit apps/desktop/.env or apps/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