Skip to main content

​
Releasing a New Version

This guide covers the full release process for Commander — from version bump to public download.

​
Prerequisites

  • Access to the cyshel-platform repository
  • GitHub CLI (gh) installed and authenticated
  • AWS CLI configured with cyshel-prod profile
  • Push access to the production branch

​
Step 1: Bump the Version

Edit apps/commander/package.json and increment the version: 
{
  "version": "0.11.0"
}
Follow semver:
  • Patch (0.10.1): bug fixes only
  • Minor (0.11.0): new features, backward compatible
  • Major (1.0.0): breaking changes

​
Step 2: Commit and Push to Production

git add -A
git commit -m "chore: bump Commander to v0.11.0"
git push origin <your-branch>:production

​
Step 3: Create a Git Tag

git tag v0.11.0
git push origin v0.11.0

​
Step 4: Create a GitHub Release

gh release create v0.11.0 \
  --title "Commander v0.11.0" \
  --notes "## What's New
- Feature A
- Feature B
- Bug fix C" \
  --target production

​
Step 5: Trigger the Build Workflow

The macOS build is a manual workflow dispatch. Trigger it with the correct inputs: 
gh workflow run "Build Commander (macOS)" \
  --ref v0.11.0 \
  -f ref=v0.11.0 \
  -f s3_bucket=cyshel-commander-releases \
  -f s3_prefix=production/0.11.0 \
  -f gha_role_arn=<your-iam-role-arn>
The gha_role_arn is the IAM role ARN for OIDC authentication. Check previous successful runs for the correct value.

​
Step 6: Monitor the Build

Watch the workflow progress: 
# List recent runs
gh run list --workflow "Build Commander (macOS)" --limit 3

# Watch a specific run
gh run view <run-id>

# Check step-by-step progress
gh api repos/Cyshel/cyshel-platform/actions/jobs/<job-id> \
  --jq '.steps[] | .name + ": " + .status + " " + (.conclusion // "")'
The build pipeline:
  1. Install dependencies — pnpm install --frozen-lockfile
  2. Build — electron-vite build
  3. Package & Notarize — electron-builder --mac (includes Apple code signing and notarization, takes 5-15 min)
  4. Upload to S3 — DMG, ZIP, blockmap, and latest-mac.yml

​
Step 7: Verify the Release

​
Check S3 artifacts

aws s3 ls s3://commander-releases-producti-releasesbucket37d32909-oew5yl0mqyo9/commander/ \
  --profile cyshel-prod | grep "0.11.0\|latest"
You should see:
  • Commander-0.11.0-universal.dmg
  • Commander-0.11.0-universal-mac.zip
  • Commander-latest-universal.dmg (updated to new version)
  • latest-mac.yml (points to new version)

​
Verify latest-mac.yml

aws s3 cp s3://commander-releases-producti-releasesbucket37d32909-oew5yl0mqyo9/commander/latest-mac.yml - \
  --profile cyshel-prod
Confirm the version field matches your release.

​
Verify auto-update

Existing Commander installations check latest-mac.yml periodically. Once the file is updated, users will be prompted to download the new version.

​
Step 8: Deploy the Website (if needed)

If the landing page changed: 
cd apps/commander-website
npx vite build

# Deploy to S3
aws s3 sync dist/ s3://commander-website-product-commanderwebsitebucketa7-a2qntjezqava/ \
  --delete --profile cyshel-prod

# Invalidate CloudFront cache
aws cloudfront create-invalidation \
  --distribution-id E3GQ4WRJOMG8PD \
  --paths "/*" \
  --profile cyshel-prod

​
Troubleshooting

​
Build fails at “Install dependencies”

The pnpm-lock.yaml is out of sync. Run pnpm install locally, commit the updated lockfile, and push again.

​
Build fails at “Configure AWS credentials”

The IAM role ARN is incorrect. Check the workflow dispatch inputs — the gha_role_arn must include the full AWS account ID.

​
Notarization takes too long

Apple notarization typically takes 5-15 minutes but can take up to 30 minutes during peak times. The build will wait.

​
Code signing fails

The signing certificate (Developer ID Application: CYSHEL CREATIVE LTD) must be imported into the CI keychain. Check that MAC_CERTIFICATE_P12 and MAC_CERTIFICATE_PASSWORD secrets are set correctly in GitHub.

​
Quick Reference

WhatCommand
Check CI statusgh run list --branch production --limit 3
Check build statusgh run list --workflow "Build Commander (macOS)" --limit 3
View run detailsgh run view <run-id>
Check S3 artifactsaws s3 ls s3://commander-releases-producti-releasesbucket37d32909-oew5yl0mqyo9/commander/ --profile cyshel-prod
Invalidate CDNaws cloudfront create-invalidation --distribution-id E3GQ4WRJOMG8PD --paths "/*" --profile cyshel-prod