Skip to main content

​
Releasing a New Version

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

​
How It Works

The release pipeline is fully automated via AWS CodePipeline: 
Push to production → CodePipeline Source
  → Orchestrator CodeBuild (dispatches GHA macOS build, polls for completion)
  → Promote CodeBuild (validates artifacts, copies staging → production, invalidates CDN, updates Homebrew tap)
Your job is to bump the version, push, and create the tag. The pipeline handles the rest.

​
Prerequisites

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

​
Step 1: Bump the Version

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

​
Step 2: Commit and Push to Production

git add apps/commander/package.json
git commit -m "chore: bump Commander to v0.14.0"
git push origin <your-branch>:production
This push triggers the CodePipeline automatically.

​
Step 3: Create a Git Tag

The tag is required by the GHA macOS build workflow. Create it on the same commit: 
git tag v0.14.0
git push origin v0.14.0

​
Step 4: Create a GitHub Release

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

​
Step 5: Monitor the Pipeline

The pipeline runs automatically after the push to production. Monitor it: 
# Watch the GHA macOS build (dispatched by CodePipeline)
gh run list --workflow "Build Commander (macOS)" --limit 3

# Watch a specific run
gh run view <run-id>
The full pipeline takes ~30 minutes:
  1. CodePipeline Source — detects production push (~1-2 min)
  2. Orchestrator CodeBuild — dispatches GHA, polls for completion (~25 min)
    • GHA builds, signs, notarizes, uploads to S3 staging
  3. Promote CodeBuild — validates artifacts, copies to production, invalidates CDN, updates Homebrew tap (~2 min)

​
Step 6: Verify the Release

# Check that the CDN serves the new version
curl -s https://releases.cyshel.com/commander/latest-mac.yml | head -1
# Should output: version: 0.14.0
Existing Commander installations check latest-mac.yml every 5 minutes. Users will be prompted to download the new version automatically.

​
Rollback

If a bad version is released, roll back to the previous version: 
aws codebuild start-build --project-name commander-rollback-production --profile cyshel-prod
This restores the previous latest-mac.yml and invalidates the CDN cache. Users on the bad version will not auto-update further, and new installs will get the previous version.

​
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.

​
Orchestrator fails to find the workflow run

The tag might not exist yet. Ensure you pushed the tag (Step 3) before the orchestrator tries to dispatch the GHA workflow.

​
DMG creation fails (hdiutil error)

This is a known intermittent issue with GitHub Actions macOS runners. Re-run the pipeline by pushing a new commit to production (e.g., an empty commit): 
git commit --allow-empty -m "chore: re-trigger release pipeline"
git push origin <your-branch>:production

​
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.

​
Pipeline failure notifications

Pipeline failures send notifications via SNS topic commander-release-failures-production. Subscribe your email or Slack webhook to receive alerts.

​
Quick Reference

WhatCommand
Check GHA build statusgh run list --workflow "Build Commander (macOS)" --limit 3
View run detailsgh run view <run-id>
Verify CDN versioncurl -s https://releases.cyshel.com/commander/latest-mac.yml | head -1
Rollbackaws codebuild start-build --project-name commander-rollback-production --profile cyshel-prod
Re-trigger pipelinePush to production (or empty commit)

​
Architecture

ComponentLocationPurpose
CodePipelineAWS (CDK)Orchestrates the full release flow
Orchestrator CodeBuildAWS (CDK)Dispatches GHA macOS build, polls for completion
Promote CodeBuildAWS (CDK)Validates + promotes artifacts, CDN invalidation, Homebrew tap
Rollback CodeBuildAWS (CDK)Restores previous release on demand
GHA build-mac.ymlGitHub ActionsmacOS build, code signing, notarization, S3 staging upload
S3 + CloudFrontAWS (CDK)Hosts release artifacts at releases.cyshel.com
SNS + EventBridgeAWS (CDK)Pipeline failure notifications
SSM ParametersAWS (CDK)Stores bucket name, distribution ID, GHA role ARN