Skip to content

Release quick reference

This page collects the short release sequences for the distributable Crystal Lattice packages. Run commands from the repository root unless a section says otherwise.

Use this page as an operational checklist. The package-owned documentation linked under Detailed release documentation remains authoritative for credentials, signing, failure recovery, versioning, and infrastructure setup.

In VS Code, open Tasks: Run Task from the Command Palette and filter for Release:. Tasks that publish, upload, create tags, or make downloads public are deliberately separate from verification and candidate-build tasks.

Current release paths

Package Official release path Published result
Crystal Lattice CLI Root release script and tag-triggered GitHub Actions matrix GitHub Release and public CLI download CDN
Desktop for macOS GitHub candidate build followed by a separate candidate-publication dispatch Signed and notarized universal DMG on the public download CDN
Mobile for iOS Local Fastlane or manually dispatched GitHub Actions workflow Internal TestFlight build
Mobile for Android No production release path is currently implemented No Google Play release

CLI

The CLI release command requires a clean main worktree whose HEAD matches origin/main. It validates the release state, creates and pushes the version tag, watches the complete platform matrix, publishes the GitHub Release, and publishes the download CDN.

Sequence Command VS Code task
1. Bump the patch version npm run release:cli:version:bump-patch Release: CLI: Bump Patch Version
2. Review, commit, and push the version change Use the normal reviewed Git workflow —
3. Preview the release without changing Git or GitHub npm run release:cli:plan Release: CLI: Plan
4. Run the complete local gate without creating a tag npm run release:cli:gate Release: CLI: Gate
5. Create and publish the release npm run release:cli Release: CLI: Publish
6. Verify the public installers and downloads npm run release:cli:smoke Release: CLI: Smoke Test

Minor and major version changes are currently edited deliberately instead of being exposed as one-click release tasks. The final tag must be crystal-lattice-cli-v<version>.

Desktop for macOS

Local candidate preparation

These commands do not publish a download:

Purpose Command VS Code task
Run the desktop release verification lane npm run desktop:macos:release:verify Release: Desktop: Verify Locally
Build an unsigned universal archive npm run desktop:macos:release:build Release: Desktop: Build Unsigned Universal Archive
Build a signed, notarized, and stapled DMG MACOS_BUILD_NUMBER=<number> npm run desktop:macos:build Release: Desktop: Build Signed and Notarized DMG Locally

The signed local build uses the current worktree and remains under the ignored desktop build/macos-release/ directory. Inspect and launch-test the actual DMG before treating it as a viable candidate.

Official GitHub candidate and publication

The official path is intentionally two-stage. The first workflow run builds and stores a candidate without publishing it. The second workflow run publishes that exact candidate by its successful workflow run ID.

Sequence Command VS Code task
1. Start the candidate build from main MACOS_BUILD_NUMBER=<number> npm run desktop:macos:release:candidate:start Release: Desktop: Start GitHub Candidate Build
2. Watch the candidate workflow npm run desktop:macos:release:watch Release: Desktop: Watch Latest GitHub Run
3. Review its commit, DMG checksum, metadata, and notarization result Inspect the completed GitHub Actions run and record its run ID —
4. Publish the reviewed candidate DESKTOP_CANDIDATE_RUN_ID=<run-id> npm run desktop:macos:release:publish:start Release: Desktop: Publish GitHub Candidate
5. Watch publication and CDN verification npm run desktop:macos:release:watch Release: Desktop: Watch Latest GitHub Run

The VS Code candidate tasks prompt for the optional build number and the required publication candidate run ID.

Mobile for iOS

Local TestFlight path

Local builds require the pinned Ruby/Bundler dependencies and an ignored mobile/crystal-lattice-control-rn/fastlane/.env containing the documented App Store Connect and read-only match credentials.

Purpose Command VS Code task
Run release verification npm run mobile:ios:release:verify Release: Mobile iOS: Verify Locally
Build a signed IPA without uploading it npm run mobile:ios:release:build Release: Mobile iOS: Build Signed IPA Locally
Verify, build, and upload to internal TestFlight TESTFLIGHT_CHANGELOG="<text>" npm run mobile:ios:release:testflight Release: Mobile iOS: Upload to TestFlight Locally

The changelog is optional. The VS Code upload task prompts for it and passes it as TestFlight's What to Test text.

GitHub Actions TestFlight path

The GitHub workflow is manual-only and always dispatches from main.

Sequence Command VS Code task
1. Run verification and create a signed IPA without uploading npm run mobile:ios:testflight:build:start Release: Mobile iOS: Start GitHub Build Only
2. Watch the build-only run npm run mobile:ios:testflight:watch Release: Mobile iOS: Watch Latest GitHub Run
3. Start the internal TestFlight upload TESTFLIGHT_CHANGELOG="<text>" npm run mobile:ios:testflight:start Release: Mobile iOS: Start GitHub TestFlight Upload
4. Watch the upload run npm run mobile:ios:testflight:watch Release: Mobile iOS: Watch Latest GitHub Run

Use the build-only mode after rotating signing or App Store Connect credentials. It proves verification, signing, archive, and export without uploading or retaining the IPA.

Mobile for Android

Android development builds exist, but production upload signing, Android Fastlane release lanes, and a Google Play deployment workflow are not implemented. Do not treat npm run mobile:android or a debug-signed Gradle release build as a Google Play release sequence.

Detailed release documentation