/socai-release

name: socai-release
description: Create, monitor, troubleshoot, and verify socai desktop GitHub releases from the command line with gh. Use when publishing a new release, triggering .github/workflows/release.yml, choosing patch/minor/major bumps, checking release workflow runs, or validating the latest macOS DMG/download redirect without using the GitHub UI.

socai release

Use this skill whenever the task is to create or inspect a socai GitHub Release, trigger the release workflow, publish a new macOS DMG, or avoid clicking through the GitHub Actions / Releases UI.

The command-line release path is the source of truth:

gh workflow run release.yml --repo socai-io/socai --ref main -f release_type=patch

A helper script wraps this command, finds the created run, watches it, and prints the resulting release:

.claude/skills/socai-release/scripts/create-release.sh patch

What the release workflow does

• Workflow: `.github/workflows/release.yml`
• Trigger: manual `workflow_dispatch`
• Required input: `release_type` = `patch`, `minor`, or `major`
• Production ref: `main`
• Test ref: `fix/release-*` branches only; build runs but publish job is skipped
• Version source: latest strict semver tag matching `vMAJOR.MINOR.PATCH`; if no tag exists, app version from `app/src-tauri/tauri.conf.json`
• Desktop artifacts: `socai-macos-universal.dmg` and `socai-windows-x86_64-setup.exe`, plus the auto-updater set `socai-macos-universal.app.tar.gz` + `.sig`, `socai-windows-x86_64-setup.exe.sig`, and `latest.json` (darwin + windows platforms)
• CLI artifacts: `install.sh`, `socai-cli-macos-universal.tar.gz` + `.sha256`, `install.ps1`, and `socai-cli-windows-x86_64.zip` + `.sha256`
• Alibaba Cloud OSS mirror: every asset is also published to `https://socai-download.oss-cn-beijing.aliyuncs.com/releases/` (`vars.SOCAI_OSS_PUBLIC_BASE_URL` in the workflow) — an immutable `releases/vX.Y.Z/` copy staged before the GitHub release, and a mutable `releases/latest/` copy promoted after it. The OSS copy of `latest.json` is rewritten so its platform URLs point at the OSS `releases/vX.Y.Z/` assets instead of GitHub.
• Production publish steps on `main`:

1. Build on GitHub Actions, in parallel: universal macOS app + DMG, universal macOS CLI, Windows CLI, and the Windows NSIS installer. 2. Require Developer ID signing + notarization secrets, and the updater minisign keypair (`TAURI_SIGNING_PRIVATE_KEY` / `TAURI_SIGNING_PRIVATE_KEY_PASSWORD`). 3. Merge the Windows updater fragment into `latest.json`, then stage the versioned release on OSS (`.github/scripts/publish-oss-release.py stage` → `releases/vX.Y.Z/`) before anything is pushed to GitHub. 4. Update app version files with `.github/scripts/set-app-version.py` and commit `chore: release socai vX.Y.Z` to `main` if needed. 5. Tag the release commit as `vX.Y.Z`. 6. Create a draft GitHub Release with generated notes (China-mirror OSS links + GitHub links) and all desktop + CLI assets. 7. Push updated `main`. 8. Publish the release by clearing draft status. 9. Promote the OSS latest release (`publish-oss-release.py promote` → overwrite `releases/latest/`, `latest.json` last). 10. Run the post-publish verify jobs: verify latest CLI installer (macOS + Windows), verify latest windows desktop installer, and verify desktop updater manifest (`latest.json` from both the OSS mirror and GitHub).

Safety rules

• Do not use the GitHub web UI for routine releases; use `gh`.
• Do not manually create GitHub releases or upload DMGs unless the workflow is broken and the user explicitly approves a fallback.
• Ask/confirm the release bump before production publishing if the user did not specify `patch`, `minor`, or `major`.
• Production releases must be dispatched from `main`; the workflow rejects other refs except `fix/release-*` test branches.
• Do not cancel an in-progress production release unless the user explicitly asks.
• Do not delete tags/releases unless the workflow failed and the user explicitly approves cleanup.
• If local files are dirty, do not include unrelated changes in release work. The workflow publishes from the remote ref, not local uncommitted files.
• The website redeploys automatically: Vercel Git integration is connected to `socai-io/socai` with production branch `main`, so the `chore: release socai vX.Y.Z` push triggers a production `socai-site` build with no manual step. Do not alter or rerun the release workflow to update `socai.io`.
• Verifying `socai.io` (the `/download`, `/download/macos`, `/download/windows`, and `/github` redirects) is a **mandatory** part of every production release — the release is not done until the redirects are confirmed resolving to the new tag's assets. Fall back to a manual `socai-site-deployment` redeploy only if that verification fails.

Preflight checks

Run from the repo root when possible.

gh auth status --hostname github.com
gh repo view socai-io/socai --json nameWithOwner,defaultBranchRef,url

git fetch origin main --tags
git status --short
git log --oneline --decorate -5 origin/main

Optional: preview the next version locally using the same bump semantics as the workflow:

release_type=patch  # patch | minor | major
latest_tag="$(git tag --list 'v*' --sort=-v:refname | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+$' | head -n 1 || true)"
base_version="${latest_tag#v}"
if [ -z "${base_version}" ]; then
  base_version="$(python3 - <<'PY'
import json
from pathlib import Path
print(json.loads(Path('app/src-tauri/tauri.conf.json').read_text())['version'])
PY
)"
fi
python3 - "${base_version}" "${release_type}" <<'PY'
import sys
base, bump = sys.argv[1:]
major, minor, patch = map(int, base.split('.'))
if bump == 'major':
    major, minor, patch = major + 1, 0, 0
elif bump == 'minor':
    minor, patch = minor + 1, 0
elif bump == 'patch':
    patch += 1
else:
    raise SystemExit(f'bad release_type: {bump}')
print(f'v{major}.{minor}.{patch}')
PY

Create a pr