Agent Skills
› brijr/gui
› release
release
GitHub用于签署、公证并发布 Gui macOS 及 Linux 构建版本,处理 Gatekeeper 调试和发布流程配置。
Trigger Scenarios
切割新版本发布
调试 Gatekeeper 或公证问题
修改 Electron-builder 或发布脚本
Install
npx skills add brijr/gui --skill release -g -y
SKILL.md
Frontmatter
{
"name": "release",
"description": "Sign, notarize, and publish a Gui macOS build, and the Linux build GitHub Actions makes from it. Use when cutting a version, debugging Gatekeeper, notarization or the Linux release workflow, or changing electron-builder \/ scripts\/release.sh \/ .github\/workflows\/release-linux.yml."
}
Release Gui
Do not publish from an agent session. Do not put certificates or notary passwords in the repo.
- Each version publishes once, tagged
v<version>. Ifpackage.json's version is already tagged, the script bumps the last number and commits it (chore: release <version> [skip ci]); commit a version yourself to pick a different one. The bump commit and tag are pushed after the upload. An installed copy reads the feed of its own version's channel. An alpha (0.1.0-alpha.N) writes onlyalpha-mac.yml; a stable version writeslatest-mac.ymland alsoalpha-mac.ymlandbeta-mac.yml(generateUpdatesFilesForAllChannels), so copies installed from an alpha update to it. A prerelease named anything else (rc) gets only its own feed, and no later release reaches it. - Work on main, with a clean tree except
www/(the site is not packaged). The script fetches first and stops iforigin/mainhas commits the local main lacks, because it ends by pushing main and the tag. - Needs, once per Mac:
- Developer ID Application in the login keychain (Xcode → Settings → Accounts → Manage Certificates), or
CSC_LINK+CSC_KEY_PASSWORD(andCSC_NAMEif several identities). - Notarization: keychain profile
gui-notary(xcrun notarytool store-credentials), orAPPLE_API_KEY+APPLE_API_KEY_ID+APPLE_API_ISSUER, orAPPLE_ID+APPLE_APP_SPECIFIC_PASSWORD+APPLE_TEAM_ID. - Wrangler logged into the Cloudflare account that owns the
gui-releasesR2 bucket (cd www && bunx wrangler login). ghsigned in to GitHub (gh auth login), for the GitHub Release.
- Developer ID Application in the login keychain (Xcode → Settings → Accounts → Manage Certificates), or
- Xcode 26+
actoolcompilesbuild/icon.icon. If Command Line Tools are selected,scripts/release.shsetsDEVELOPER_DIRto/Applications/Xcode.app/Contents/Developer. - First run
bun run smoke:agents(one real turn per installed agent, on your own agent usage) and look into any FAIL: an agent update may have broken Gui. Then runbun run release(scripts/release.sh). It runsbun run check, builds, thenelectron-builder --mac --publish never. CSC_IDENTITY_AUTO_DISCOVERYmust stay unset for a signed build. Unsigned/ad-hoc builds (CSC_IDENTITY_AUTO_DISCOVERY=false bun run dist) get a new signature each time; macOS then re-prompts for the keychain item and the preview stays blank until that is answered.- After the build:
scripts/check-packaged-app.shimports each agent adapter and each module the main process imports from the packagednode_modules(add a new adapter or main-process dependency to its list),codesign --verify --deep --strictonGui.app, staple the DMG, confirmrelease/$channel-mac.ymlexists. The script refuses to publish if any of that fails. - Uploads: the zip first. Then the blockmap and the DMG, as
Gui-<version>-arm64.dmgandGui-<channel>-arm64.dmg; a stable release also asGui-arm64.dmg, whichusegui.com/downloadserves in place of the alpha's once it exists. Everyrelease/*-mac.ymlgoes last and is read back from the site before anything is tagged. - Before running it, add the release to the top of
www/src/changelog.ts(the site's /changelog): the version the script will release, today's date, and a few plain bullets of what a user would notice. The script stops before building if that entry is missing, and after pushing the tag it creates a GitHub Release with those bullets as its notes (--prereleasefor alphas). Deploy the site (cd www && bun run deploy) so /changelog shows it. - CI
release-dry-runonly packs whenCSC_LINKis set; without secrets it checkselectron-builder.ymland thatscripts/release.shparses.
Linux
The Linux build is made in GitHub Actions from the tag, by .github/workflows/release-linux.yml; nothing runs on the Mac.
- The GitHub Release that
scripts/release.shcreates last starts it. Onubuntu-24.04(x64) andubuntu-24.04-arm(arm64), each build job checks thatpackage.jsonat the tag has the tag's version, runsbun run check, builds withGUI_OFFICIAL_BUILD=1(asrelease.shdoes) and packages an AppImage and a.deb(electron-builder --linux; node-pty compiles on the runner). Thenscripts/check-packaged-app.shimports each adapter and main-process module fromrelease/linux-unpacked(linux-arm64-unpacked), andscripts/check-launch.tsstarts the AppImage under xvfb, waits for its window to load and quits it with SIGTERM, which must end it with exit code 0. A failed check stops the run before anything is uploaded. - One publish job then attests build provenance for the AppImages and
.debs, writesSHA256SUMS, and runsscripts/publish-linux.sh. It refuses a version thatusegui.com/releases/<channel>-mac.ymldoesn't name: Linux follows the Mac's newest release on its channel, so re-running an old tag can't roll anyone back. It uploadsGui-<version>-x86_64.AppImage,Gui-<version>-arm64.AppImage,Gui-<version>-amd64.debandGui-<version>-arm64.deb, checks that the site answers a Range request with 206, uploads the copies/download/<file>serves (Gui-<channel>-x86_64.AppImageand so on; a stable release alsoGui-x86_64.AppImageand so on), and uploads the feeds<channel>-linux.yml(x64) and<channel>-linux-arm64.ymllast, reading them back from the site. Last, it attaches the AppImages,.debs andSHA256SUMSto the GitHub Release. - Repository secrets, read only by the publish step:
R2_ACCESS_KEY_ID,R2_SECRET_ACCESS_KEYandCLOUDFLARE_ACCOUNT_ID(the account inwww/wrangler.jsonc). The first two come from one Cloudflare account API token limited to thegui-releasesbucket, with R2 object read and write: the access key is the token's id and the secret is the SHA-256 (hex) of the token's value.scripts/publish-linux.shuploads with curl through R2's S3 API; Wrangler won't take a token limited to one bucket. - To run it again, re-run the failed jobs in Actions (same workflow file), or
gh workflow run release-linux.yml -f tag=v<version>, which usesmain's workflow file to build the tag. Uploads overwrite what an earlier run put there. - The AppImage updates itself from the Linux feeds. A
.debinstall never checks; Check for Updates tells the user to download the new version (src/main/updates.ts). On Linux,usegui.com/downloadis the download page for the browser's processor (www/src/pages/download/[page].astro), whose links are the worker's/download/<file>. Deploy the site with that page only once a Linux build is in the bucket.
Human review before changing this path.
Version History
- eecbbe2 Current 2026-11-19 21:09


