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. There is no manual tag creation, no manual approval gate, and no GitHub release step:

Merge dev → production (push)
  → CodePipeline Source (triggers on every push to production)
  → Build: orchestrator CodeBuild
      reads the version from apps/commander/package.json,
      creates the commander@X.Y.Z git tag,
      dispatches the "Build Commander (macOS)" GitHub Actions workflow,
      polls every 30 s (up to ~40 min) until it completes
  → Promote: promote CodeBuild
      validates the staged artifacts, copies staging → production,
      invalidates the CDN, updates the Homebrew tap

Your job is to bump the version on dev and merge to production. The pipeline handles everything else, including the git tag.

Prerequisites

Push access to the production branch of cyshel-platform
The cyshel-prod AWS profile (for monitoring and rollback)
GitHub CLI (gh) authenticated, if you want to watch the macOS build

Step 1: bump the version on dev

Edit apps/commander/package.json and increment the version:

{
  "version": "0.27.0"
}

Follow semver:

Patch (0.26.1): bug fixes only
Minor (0.27.0): new features, backward compatible
Major (1.0.0): breaking changes

Commit and push to dev as usual. The version in package.json is the single source of truth — the pipeline reads it to name the tag and the artifacts.

Step 2: merge dev into production

git checkout production
git pull origin production
git merge dev
git push origin production

The push to production is the only trigger. The pipeline creates and pushes the commander@X.Y.Z tag itself — do not create tags manually.

Step 3: monitor the pipeline

# Pipeline stage status (Source → Build → Promote)
AWS_PROFILE=cyshel-prod aws codepipeline get-pipeline-state \
  --name commander-release-production \
  --region us-east-1 \
  --query 'stageStates[*].{stage:stageName,status:latestExecution.status}' \
  --output table

# Watch the GHA macOS build the orchestrator dispatched
gh run list --workflow "Build Commander (macOS)" --limit 3
gh run view <run-id>

The Build stage dominates the runtime: the GitHub Actions job builds with electron-vite, signs and notarizes with electron-builder, verifies the signature and Gatekeeper assessment, then uploads to S3 staging. The orchestrator polls every 30 seconds for up to ~40 minutes; the GHA job itself has a 45-minute timeout. The Promote stage has a 10-minute timeout.

Step 4: verify the release

# The CDN should serve the new version
curl -s https://releases.cyshel.com/commander/latest-mac.yml | head -1
# Expected: version: 0.27.0

Also confirm:

The commander@0.27.0 tag exists on GitHub (created by the pipeline).
The Homebrew tap (Cyshel/homebrew-tap, Casks/commander.rb) shows the new version and SHA-256. The tap update retries three times and is non-fatal — check it explicitly if it matters for this release.

Running Commander installations check latest-mac.yml 10 seconds after launch and every 5 minutes thereafter, download the update in the background, and prompt the user to install (with snooze and install-when-idle options).

Rollback

If a bad version ships, restore the previous update manifest:

AWS_PROFILE=cyshel-prod aws codebuild start-build \
  --project-name commander-rollback-production \
  --region us-east-1

This restores the previous latest-mac.yml from commander/rollback/ and invalidates the CDN. Clients already on the bad version are not downgraded, but no new clients are offered it.

Troubleshooting

Build fails at “Install dependencies”

The GHA workflow runs pnpm install --frozen-lockfile, so an out-of-sync pnpm-lock.yaml fails the build. Run pnpm install locally, commit the updated lockfile to dev, and merge to production again.

Retrying a failed stage

You don’t need a new commit — retry the failed stage in place:

# Get the execution ID
AWS_PROFILE=cyshel-prod aws codepipeline get-pipeline-state \
  --name commander-release-production \
  --region us-east-1 \
  --query 'stageStates[?stageName==`Build`].latestExecution.pipelineExecutionId' \
  --output text

# Retry
AWS_PROFILE=cyshel-prod aws codepipeline retry-stage-execution \
  --pipeline-name commander-release-production \
  --stage-name Build \
  --pipeline-execution-id <EXECUTION_ID> \
  --retry-mode FAILED_ACTIONS \
  --region us-east-1

Retrying Build is safe: the orchestrator is idempotent. If the tag already exists and the staged artifacts are present, it skips the build; if the tag exists but artifacts are missing, it re-dispatches the GHA workflow.

Promote fails with “Missing artifact” or “Version mismatch”

Promote validates that latest-mac.yml, Commander-X.Y.Z-universal.dmg, and Commander-X.Y.Z-universal-mac.zip exist in commander/staging/X.Y.Z/ and that the manifest version matches package.json. A failure here usually means the GHA upload was incomplete — retry the Build stage first, then Promote.

Code signing or notarization fails

Signing uses a certificate imported from the MAC_CERTIFICATE_P12 / MAC_CERTIFICATE_PASSWORD GitHub secrets; notarization uses APPLE_ID, APPLE_APP_SPECIFIC_PASSWORD, and APPLE_TEAM_ID. Check the “Import signing certificate” and “Package & Notarize” steps in the GHA run log.

Pipeline failure notifications

Failures (any stage) publish to the SNS topic commander-release-failures-production with the execution ID. Subscribe an email or Slack webhook to that topic to be alerted. There are no success notifications.

Quick reference

What	Command
Pipeline status	`aws codepipeline get-pipeline-state --name commander-release-production --region us-east-1`
Watch GHA build	`gh run list --workflow "Build Commander (macOS)" --limit 3`
Verify CDN version	`curl -s https://releases.cyshel.com/commander/latest-mac.yml \| head -1`
Retry a failed stage	`aws codepipeline retry-stage-execution --pipeline-name commander-release-production …`
Rollback	`aws codebuild start-build --project-name commander-rollback-production --region us-east-1`
Re-trigger from scratch	Push to `production` (e.g. `git commit --allow-empty`)

All AWS commands need AWS_PROFILE=cyshel-prod.

Architecture

Component	Location	Purpose
CodePipeline	AWS (CDK)	`commander-release-production` — Source → Build → Promote, no approvals
Orchestrator CodeBuild	AWS (CDK)	Creates the `commander@X.Y.Z` tag, dispatches GHA, polls for completion
Promote CodeBuild	AWS (CDK)	Validates + promotes artifacts, CDN invalidation, Homebrew tap
Rollback CodeBuild	AWS (CDK)	Restores the previous manifest on demand
GHA `build-mac.yml`	GitHub Actions	macOS build, code signing, notarization, S3 staging upload
S3 + CloudFront	AWS (CDK)	Hosts release artifacts at `releases.cyshel.com`
SNS + EventBridge	AWS (CDK)	Pipeline failure notifications

The CDK stack is infrastructure/lib/stacks/commander-releases-stack.ts; the full reference lives at docs/infrastructure/commander-releases.md.

Getting Started

Features

Guides

Reference

Releasing a new version

How it works

Prerequisites

Step 1: bump the version on dev

Step 2: merge dev into production

Step 3: monitor the pipeline

Step 4: verify the release

Rollback

Troubleshooting

Build fails at “Install dependencies”

Retrying a failed stage

Promote fails with “Missing artifact” or “Version mismatch”

Code signing or notarization fails

Pipeline failure notifications

Quick reference

Architecture

​How it works

​Prerequisites

​Step 1: bump the version on dev

​Step 2: merge dev into production

​Step 3: monitor the pipeline

​Step 4: verify the release

​Rollback

​Troubleshooting

​Build fails at “Install dependencies”

​Retrying a failed stage

​Promote fails with “Missing artifact” or “Version mismatch”

​Code signing or notarization fails

​Pipeline failure notifications

​Quick reference

​Architecture

How it works

Prerequisites

Step 1: bump the version on dev

Step 2: merge dev into production

Step 3: monitor the pipeline

Step 4: verify the release

Rollback

Troubleshooting

Build fails at “Install dependencies”

Retrying a failed stage

Promote fails with “Missing artifact” or “Version mismatch”

Code signing or notarization fails

Pipeline failure notifications

Quick reference

Architecture