socai-release
Skill257 starsChanged 50 days agoApache-2.0View on GitHub
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.
In this repository6 other files it gives its agents.
- AGENTS.mdAGENTS.md
- clean-targetsSkill
- socai-model-syncSkill
- socai-site-deploymentSkill
- rsiSkill
- socai-cliSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
16 rules. About 0 are common, 8 are distinctive, and 8 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈8
Distinctive · estimate
This author's own choices. Worth a look.
8
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 8
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 …
- Very specific: line 28
Test ref: fix/release-* branches only.
- Very specific: line 37
Update app version files with .github/scripts/set-app-version.py and commit chore: release socai vX.Y.Z to main if needed.
- Distinctive: line 39
Create a draft GitHub Release with generated notes (China-mirror OSS links + GitHub links) and all desktop + CLI assets.
- Very specific: line 43
Run the post-publish verify jobs: verify latest CLI installer (macOS + Windows), verify latest windows desktop installer, and verify …
- Very specific: line 47
Do not use the GitHub web UI for routine releases.
- Distinctive: line 48
Do not manually create GitHub releases or upload DMGs unless the workflow is broken and the user explicitly approves a fallback.
- Very specific: line 49
Ask/confirm the release bump before production publishing if the user did not specify patch, minor, or major.
- Distinctive: line 51
Do not cancel an in-progress production release unless the user explicitly asks.
- Distinctive: line 52
Do not delete tags/releases unless the workflow failed and the user explicitly approves cleanup.
- Distinctive: line 53
If local files are dirty, do not include unrelated changes in release work.
- Distinctive: line 59
Run from the repo root when possible.
- Very specific: line 129
Use minor or major instead of patch only when requested.
- Distinctive: line 137
After the GitHub release verification, confirm the live site responds and every redirect resolves.
- Very specific: line 154
Only use a branch named fix/release-*.
- Distinctive: line 203
After a successful production run:
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
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=patchA helper script wraps this command, finds the created run, watches it, and prints the resulting release:
.claude/skills/socai-release/scripts/create-release.sh patchWhat the release workflow does
- Workflow:
.github/workflows/release.yml - Trigger: manual
workflow_dispatch - Required input:
release_type=patch,minor, ormajor - 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 fromapp/src-tauri/tauri.conf.json - Desktop artifacts:
socai-macos-universal.dmgandsocai-windows-x86_64-setup.exe, plus the auto-updater setsocai-macos-universal.app.tar.gz+.sig,socai-windows-x86_64-setup.exe.sig, andlatest.json(darwin + windows platforms) - CLI artifacts:
install.sh,socai-cli-macos-universal.tar.gz+.sha256,install.ps1, andsocai-cli-windows-x86_64.zip+.sha256 - Alibaba Cloud OSS mirror: every asset is also published to
https://socai-downloads.oss-cn-hangzhou.aliyuncs.com/releases/(vars.SOCAI_OSS_PUBLIC_BASE_URLin the workflow) — an immutablereleases/vX.Y.Z/copy staged before the GitHub release, and a mutablereleases/latest/copy promoted after it. The OSS copy oflatest.jsonis rewritten so its platform URLs point at the OSSreleases/vX.Y.Z/assets instead of GitHub. - Production publish steps on
main:- Build on GitHub Actions, in parallel: universal macOS app + DMG, universal macOS CLI, Windows CLI, and the Windows NSIS installer.
- Require Developer ID signing + notarization secrets, and the updater minisign keypair (
TAURI_SIGNING_PRIVATE_KEY/TAURI_SIGNING_PRIVATE_KEY_PASSWORD). - 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. - Update app version files with
.github/scripts/set-app-version.pyand commitchore: release socai vX.Y.Ztomainif needed. - Tag the release commit as
vX.Y.Z. - Create a draft GitHub Release with generated notes (China-mirror OSS links + GitHub links) and all desktop + CLI assets.
- Push updated
main. - Publish the release by clearing draft status.
- Promote the OSS latest release (
publish-oss-release.py promote→ overwritereleases/latest/,latest.jsonlast). - Run the post-publish verify jobs: verify latest CLI installer (macOS + Windows), verify latest windows desktop installer, and verify desktop updater manifest (
latest.jsonfrom 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, ormajor. - Production releases must be dispatched from
main; the workflow rejects other refs exceptfix/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/socaiwith production branchmain, so thechore: release socai vX.Y.Zpush triggers a productionsocai-sitebuild with no manual step. Do not alter or rerun the release workflow to updatesocai.io. - Verifying
socai.io(the/download,/download/macos,/download/windows, and/githubredirects) 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 manualsocai-site-deploymentredeploy 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/mainOptional: 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}')
PYCreate a production release
Preferred helper:
.claude/skills/socai-release/scripts/create-release.sh patchEquivalent raw gh path:
gh workflow run release.yml \
--repo socai-io/socai \
--ref main \
-f release_type=patch
sleep 8
run_id="$(gh run list \
--repo socai-io/socai \
--workflow release.yml \
--branch main \
--event workflow_dispatch \
--limit 1 \
--json databaseId \
--jq '.[0].databaseId')"
gh run watch "${run_id}" --repo socai-io/socai --exit-statusUse minor or major instead of patch only when requested.
Verify the website deployment (mandatory)
The website is not an optional follow-up — verifying it is a required release gate.
Vercel Git integration is connected to socai-io/socai with production branch main (project socai-site, scope socai-d83824c8). The release workflow's push of chore: release socai vX.Y.Z to main therefore triggers a production socai-site build automatically, so no manual deploy is normally needed. The site does not display a version number (the hero release-meta line was removed); the /download* redirects point at the Alibaba Cloud OSS mirror's mutable releases/latest/ objects, which the release workflow's promote OSS latest release step overwrites right after the GitHub release is published — the downloads serve the new version as soon as that promotion completes, with no site change involved.
After the GitHub release verification, confirm the live site responds and every redirect resolves. The auto-deploy usually finishes within ~1 minute of the main push; allow for that and re-check if it is still mid-build.
curl -sI https://socai.io/ | grep -iE '^HTTP' # 200
curl -sI https://www.socai.io/ | grep -iE '^HTTP|^location' # 308 -> https://socai.io/
curl -sI https://socai.io/download | grep -iE '^HTTP|^location' # 307 -> OSS releases/latest/socai-macos-universal.dmg
curl -sI https://socai.io/download/macos | grep -iE '^HTTP|^location' # 307 -> OSS releases/latest/socai-macos-universal.dmg
curl -sI https://socai.io/download/windows | grep -iE '^HTTP|^location' # 307 -> OSS releases/latest/socai-windows-x86_64-setup.exe
curl -sI https://socai.io/github | grep -iE '^HTTP|^location' # 307 -> github.com/socai-io/socaiThe release is complete only when all six checks above pass and the /download* targets serve the just-published tag's build (see the redirect-resolution check in Verify the published release). The OSS latest/ URLs are stable and do not embed the tag, so that tag check is a content-identity comparison, not a URL match.
If the site has not updated after the auto-deploy should have finished, fall back to a manual redeploy: switch to the socai-site-deployment skill and deploy the production socai-site project with SOCAI_RELEASE_VERSION=X.Y.Z. Do not rerun the GitHub release workflow to fix a site-only lag, and do not add website-deploy steps to the release workflow — the Git integration already performs the deploy. Note the redirect destinations are static OSS URLs in site/vercel.json: if the redirects respond correctly but /download* serves a stale build, the problem is the OSS releases/latest/ objects (the workflow's promote OSS latest release step), and a site redeploy will not fix it.
Test the release workflow without publishing
Only use a branch named fix/release-*. The workflow will build, use ad-hoc signing if production signing secrets are unavailable, and skip the publish job.
.claude/skills/socai-release/scripts/create-release.sh patch --ref fix/release-some-branchor:
gh workflow run release.yml \
--repo socai-io/socai \
--ref fix/release-some-branch \
-f release_type=patchMonitor or troubleshoot an existing run
List recent release runs:
gh run list --repo socai-io/socai --workflow release.yml --limit 10Watch a run:
gh run watch RUN_ID --repo socai-io/socai --exit-statusView details/logs:
gh run view RUN_ID --repo socai-io/socai
gh run view RUN_ID --repo socai-io/socai --log-failedCommon failure notes:
main moved while the release was building: rerun from the latestmainafter confirming the move was expected.- Missing Apple secrets on
main: production release cannot proceed until signing/notarization secrets are configured. - Build/notarization failure after no
mainpush: inspect logs; the workflow attempts to clean up draft release/tag state. - Failure after
main was already updated: leave state for manual inspection; do not delete the release/tag without explicit approval. - Failure in
stage versioned release on Alibaba Cloud OSS: nothing was published yet (no tag, no release, nomainpush); fix the OSS issue and rerun the workflow from scratch. - Failure in
promote OSS latest release: the GitHub release is already live but OSSreleases/latest/— and therefore the site/download*redirects — still serve the previous build. Rerunning the release job trips themain movedguard; surface it and only promote manually (.github/scripts/publish-oss-release.py promote) with explicit approval. - A post-publish
verify *job failure means the release is already published; each verifier retries internally (~2 minutes), so a hard failure is usually a real asset/manifest problem, not propagation lag. Diagnose before touching release state. - If the
/download*redirects serve a stale build after a release, check the run'spromote OSS latest releasestep first — do not rerun the release for that. Use thesocai-site-deploymentskill (redeploy withSOCAI_RELEASE_VERSIONset to the published version) only for site-level failures such as bad redirect rules or HTTP errors onsocai.io.
Verify the published release
After a successful production run:
gh release view --repo socai-io/socai \
--json tagName,name,url,isDraft,isPrerelease,publishedAt,assets \
--jq '{tagName,name,url,isDraft,isPrerelease,publishedAt,assets:[.assets[].name]}'Expected:
isDraft: falseisPrerelease: false- Asset list includes the desktop set —
socai-macos-universal.dmg,socai-macos-universal.app.tar.gz+.sig,socai-windows-x86_64-setup.exe+.sig,latest.json— and the CLI set —install.sh,socai-cli-macos-universal.tar.gz+.sha256,install.ps1,socai-cli-windows-x86_64.zip+.sha256(12 assets total)
Verify download redirects. The site's /download* redirects resolve to the OSS mirror's stable releases/latest/ URLs, which do not embed the tag — so "redirects resolve to the new tag's assets" means each latest/ object is byte-identical to the immutable releases/vX.Y.Z/ copy staged for this release (compare ETag / x-oss-hash-crc64ecma / Content-Length), and/or matches the GitHub asset size:
tag="$(gh release view --repo socai-io/socai --json tagName --jq '.tagName')"
oss_base="https://socai-downloads.oss-cn-hangzhou.aliyuncs.com/releases"
curl -I -L --max-time 30 -o /dev/null -w 'code=%{http_code}\nfinal=%{url_effective}\n' https://socai.io/download
# code=200, final=${oss_base}/latest/socai-macos-universal.dmg
# The OSS latest updater manifest embeds the promoted version:
curl -fsSL -H 'Cache-Control: no-cache' "${oss_base}/latest/latest.json" \
| python3 -c 'import json,sys; print(json.load(sys.stdin)["version"])' # X.Y.Z of ${tag}
# latest/ objects must be identical to the versioned copies:
for asset in socai-macos-universal.dmg socai-windows-x86_64-setup.exe; do
latest="$(curl -sI "${oss_base}/latest/${asset}" | tr -d '\r' | grep -iE '^(etag|x-oss-hash-crc64ecma|content-length):' | sort)"
tagged="$(curl -sI "${oss_base}/${tag}/${asset}" | tr -d '\r' | grep -iE '^(etag|x-oss-hash-crc64ecma|content-length):' | sort)"
if [ -n "${latest}" ] && [ "${latest}" = "${tagged}" ]; then
echo "ok: latest/${asset} matches ${tag}"
else
printf 'MISMATCH %s\nlatest:\n%s\ntagged:\n%s\n' "${asset}" "${latest}" "${tagged}"
fi
done
# GitHub's own latest pointer must also resolve to the new tag:
curl -sSI https://github.com/socai-io/socai/releases/latest/download/socai-macos-universal.dmg | grep -F "/releases/download/${tag}/socai-macos-universal.dmg"
curl -sSI https://github.com/socai-io/socai/releases/latest/download/socai-windows-x86_64-setup.exe | grep -F "/releases/download/${tag}/socai-windows-x86_64-setup.exe"Cross-check against GitHub asset sizes if anything looks off (each size must equal the matching OSS Content-Length):
gh release view "${tag}" --repo socai-io/socai --json assets \
--jq '.assets[] | select(.name == "socai-macos-universal.dmg" or .name == "socai-windows-x86_64-setup.exe") | "\(.name) \(.size)"'The OSS checks confirm the mirror the site actually serves; the GitHub checks confirm the GitHub latest pointer (used by the updater fallback and the CLI installers). Confirm the site checks as a mandatory step (see Verify the website deployment).
Optional artifact check:
tag="$(gh release view --repo socai-io/socai --json tagName --jq '.tagName')"
mkdir -p "/tmp/socai-release-${tag}"
gh release download "${tag}" \
--repo socai-io/socai \
--pattern socai-macos-universal.dmg \
--dir "/tmp/socai-release-${tag}" \
--clobber
shasum -a 256 "/tmp/socai-release-${tag}/socai-macos-universal.dmg"Reporting back
Include:
- Release type (
patch,minor, ormajor) - Ref used (
mainfor production) - GitHub Actions run URL and conclusion
- Published tag/version and release URL
- Asset presence (desktop:
socai-macos-universal.dmg+socai-windows-x86_64-setup.exe, updatersocai-macos-universal.app.tar.gz+.sig,socai-windows-x86_64-setup.exe.sig,latest.json; CLI:install.sh,socai-cli-macos-universal.tar.gz+.sha256,install.ps1,socai-cli-windows-x86_64.zip+.sha256) /download+/download/macos+/download/windowsverification summarysocai.iosite verification summary (mandatory):/,www,/download,/download/macos,/download/windows,/githuball behave as expected, and the OSSreleases/latest/download targets match the published tag's staged copies- Whether the Git-integration auto-deploy was sufficient, or a manual
socai-site-deploymentredeploy fallback was needed - Any failures, cleanup performed, or manual blockers
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

