Pages · Claude Digital Twin
Release guide
This is the operator's checklist for cutting a real signed release. The release workflow at .github/workflows/release.yml runs on every v*.*.* tag push; this doc covers what secrets to set so it actually produces signed artifacts.
Until these secrets are configured, releases produce unsigned binaries. macOS will Gatekeeper-block them on first launch and Windows SmartScreen will warn users. The app still works once the user right-clicks → Open (mac) or clicks "Run anyway" (Windows), but it's a poor first-impression experience.
What gets built on a tag push
| Artifact | Path in Release | Source |
|---|---|---|
| macOS arm64 | claude-twin-<ver>-arm64.dmg | desktop/dist/ |
| macOS x64 | claude-twin-<ver>.dmg | desktop/dist/ |
| Windows x64 | claude-twin-<ver>-setup.exe | desktop/dist/ |
| Linux x64 | claude-twin-<ver>.AppImage | desktop/dist/ |
| Update feed | latest-mac.yml, latest.yml, latest-linux.yml | electron-updater |
| Extension | claude-twin-extension-v<ver>.zip | extension/ zipped |
| MCP server | @claude-twin/mcp-server@<ver> on npm | mcp-server/ |
Required secrets
Set in Settings → Secrets and variables → Actions on the repo.
macOS code signing + notarization
| Secret | What it is | How to get it |
|---|---|---|
MAC_CSC_LINK | Base64-encoded .p12 of your "Developer ID Application" certificate | See "Get a Developer ID cert" below |
MAC_CSC_KEY_PASSWORD | Password for the .p12 | You set it during export |
APPLE_ID | The Apple ID email tied to your developer account | from id.apple.com |
APPLE_APP_SPECIFIC_PASSWORD | App-specific password for that Apple ID | https://appleid.apple.com → Sign-In and Security → App-Specific Passwords |
APPLE_TEAM_ID | Your developer team's 10-character team id | https://developer.apple.com/account → Membership |
Get a Developer ID cert
- Sign in to developer.apple.com — needs a paid Developer Program membership (US$99/yr).
- Certificates →
+→ Developer ID Application. - Generate a CSR with Keychain Access → Certificate Assistant → "Request a Certificate from a Certificate Authority" (saved to disk, no email).
- Upload the CSR; download the resulting
.cer. - Double-click to install in Keychain Access.
- In Keychain Access, find "Developer ID Application: Your Name (TEAMID)", expand it, right-click the private key, Export. Choose
.p12, set a password. - Base64-encode for GitHub:
base64 -i developer-id.p12 -o cert.p12.base64→ contents go intoMAC_CSC_LINK.
Windows code signing
| Secret | What it is |
|---|---|
WIN_CSC_LINK | Base64-encoded .pfx of your code-signing certificate |
WIN_CSC_KEY_PASSWORD | Password for the .pfx |
Buy a code-signing certificate from a trusted CA — DigiCert, Sectigo, SSL.com all sell EV certs ($300-500/yr) which avoid the SmartScreen "publisher unknown" warning. Standard OV certs ($75-150/yr) work but Microsoft will warn until enough installs accumulate reputation.
The cert vendor will deliver a .pfx. Encode like macOS: base64 -i cert.pfx -o cert.pfx.base64 → contents go into WIN_CSC_LINK.
npm publish
| Secret | What it is |
|---|---|
NPM_TOKEN | Automation token with publish access to @claude-twin/mcp-server |
- https://npmjs.com → your profile → Access Tokens → "Generate New Token" → Automation type.
- The release workflow uses npm provenance, so make sure your repo allows it:
npm publish --provenancerequires the workflow runs on apull_requestorpushevent with proper OIDC scopes (already configured in our workflow).
Cutting a release (once secrets are set)
The workflow takes ~25 minutes (mac-14 build is the slowest leg; cross-arch dmg + notarization).
After publish
- Verify the GitHub Release page has all six artifacts attached.
- Verify electron-updater feed is reachable:
curl -L https://github.com/fadymondy/claude-twin/releases/latest/download/latest-mac.yml. - Verify npm:
npm view @claude-twin/mcp-server versionreturns the new version. - Verify auto-update flow: install the previous version, launch, wait for the update prompt.
Failure modes
- Notarization fails (
Apple service error: ITMS-90000): Apple ID password rotated, or app-specific password expired. Regenerate at appleid.apple.com. - Windows SmartScreen still warns despite signing: standard OV cert needs to build reputation. Either wait for ~50 successful installs, or upgrade to EV.
Cannot compute electron version from installed node modules:electrondep indesktop/package.jsonis using a range (^33.x.y). Pin to an exact version.@claude-twin/mcp-serverpublish fails with 403: NPM_TOKEN doesn't have publish access, or 2FA isn't auto-token type.