macOS direct-download release
The desktop package builds one universal Apple Silicon and Intel application for macOS 14 or later. The distributable is an app-only DMG. Fastlane is the local source of truth for signing, notarization, stapling, and release checks; the GitHub Actions workflow calls the same lane.
The first release completed both the local and hosted GitHub Actions paths. Local review builds use the same release lane; publication is a separate explicit action.
The local and hosted universal Developer ID build, notarization, stapling,
Gatekeeper and launch smoke have been verified. Build-only run 36633536807
produced 0.9.0 (4) from clean source
1a04b8689eab0821727be2c3efc9213e57ebafe7 on September 29, 2026.
Publication run 36685765746 published that exact candidate on September 30
through the existing download CDN.
The DMG contains the application and an Applications shortcut. Mount it, copy Crystal Lattice Desktop to Applications and launch it there; Metro and a source checkout are not required. The DMG does not install the CLI. Start a compatible runtime separately and use the existing Desktop connection flow.
Current source/native website captures may include newer product changes. They do not establish the contents of a previously published DMG; validate a fresh signed candidate before publishing those changes.
Local review DMG
From the repository root, build an installable review DMG with:
npm run desktop:macos:build
This delegates to the desktop package's macos:build script and the existing
Ruby wrapper, then runs fastlane mac release. The npm script enables all
release verification and forces read-only signing retrieval. It builds the
current working tree, including uncommitted changes. It neither installs nor
publishes the result.
Set up Node/npm dependencies, the pinned Ruby/Bundler environment, and
CocoaPods first. Copy fastlane/.env.example to the ignored fastlane/.env
inside the desktop package and restrict it to its owner (chmod 600).
Configure the existing credentials; a new certificate or signing repository is
not needed while the current ones remain valid:
| Desktop setting | Existing signing configuration |
|---|---|
APPLE_TEAM_ID |
Existing Apple team |
DESKTOP_MATCH_GIT_URL, DESKTOP_MATCH_GIT_BRANCH |
Existing mobile MATCH_GIT_URL, MATCH_GIT_BRANCH |
MATCH_PASSWORD |
Existing signing-repository encryption password |
DESKTOP_APP_STORE_CONNECT_KEY_ID, DESKTOP_APP_STORE_CONNECT_ISSUER_ID |
Existing mobile APP_STORE_CONNECT_KEY_ID, APP_STORE_CONNECT_ISSUER_ID |
DESKTOP_APP_STORE_CONNECT_KEY_PATH |
Absolute path to the existing owner-only .p8 file; alternatively use the documented inline-key variables |
DEVELOPER_ID_APPLICATION_IDENTITY |
Exact Developer ID Application identity name or SHA-1 fingerprint used to sign the DMG |
MACOS_MARKETING_VERSION, MACOS_BUILD_NUMBER |
Deliberately selected version and positive integer build number |
Keep the desktop bundle ID from the example; do not copy the mobile bundle ID.
The signing repository also requires working SSH access. A configured
MATCH_GIT_PRIVATE_KEY may refer to the existing read-only deploy key; otherwise
the local SSH configuration is used. Enter any Keychain password only at the
local prompt. Never put credentials in command arguments, documentation, or
tracked files. Fastlane loads the package-local .env; ignored files are not
automatically shared between worktrees.
An exported setting overrides the local .env, for example:
MACOS_BUILD_NUMBER=5 npm run desktop:macos:build
The lane checks credentials before verification/build work. It preserves the
preceding build/macos-release/ directory in a unique directory under
build/macos-release-history/ before starting the archive. This includes old
DMGs, checksums and metadata, even if the new attempt fails. History is retained
until explicitly removed, so account for archive disk usage.
Success prints the absolute DMG path, version/build, checksum, metadata and
notarization-log paths, source cleanliness, and the exact open command.
Output remains under build/macos-release/. Open the DMG, quit the existing
app, then drag the app onto its Applications shortcut to install. The CLI is
separate and Metro is not required.
Before accepting a new candidate, mount the actual DMG and check its app's
signature, Gatekeeper acceptance, and ordinary launch without Metro.
Notarization does not prove runtime correctness. Preserve a working DMG until
this launch check passes. Local uncommitted builds have
source_tree_clean = false; the public candidate validator still requires a
clean reviewed source commit. The local command does not change the public
version or website download.
/var/folders/j5/g0_m7cb52q935c_px994vbp80000gn/T/crystal-roadmap-move-j8dazge7/0-theirs.txt
Local toolchain and lanes
From desktop/crystal-lattice-control-desktop-rn, use Node 20+, Ruby 3.4.10,
and Xcode 26.1. The GitHub-hosted macos-26 image uses Xcode 26.1.1.
npm ci
npm run ruby:check
RBENV_VERSION="$(cat .ruby-version)" rbenv exec bundle install
npm run pod-install
npm run release:verify
npm run release:build
The npm Ruby wrapper accepts an already-correct Ruby/Bundler environment, as
used by CI, and otherwise uses the .ruby-version installation through
rbenv exec. It fails with the expected and detected versions before invoking
CocoaPods or Fastlane. GUI-launched Xcode sources macos/.xcode.env and the
ignored .xcode.env.local so Node can be resolved from the repository
.nvmrc without relying on the GUI process PATH.
verify runs build-number tests, TypeScript, Jest, and Xcode Release
configuration inspection. build creates an unsigned universal archive for
checking bundled resources, metadata, and native architectures without Apple
credentials. release runs verification, downloads signing from match
read-only, creates a signed archive and app-only DMG, submits the DMG for
notarization, staples its ticket, checks Gatekeeper, and writes its SHA-256
checksum and release-metadata.json under the ignored
build/macos-release/ directory.
Do not run mac setup_signing on CI. The Developer ID Application certificate
was created manually by the Apple Developer Account Holder. For this first
release, import its paired .cer and .p12 into the existing private
crystal-lattice-ios-signing repository with:
bash scripts/import_developer_id_signing.sh \
/path/to/developerID_application.cer \
/path/to/Certificates.p12
The helper uses the existing ignored mobile fastlane/.env for signing
repository and App Store Connect API-key settings. It checks the selected
certificate fingerprint and private-key pairing; enter the .p12 export
password only at the local OpenSSL prompt. At Fastlane's three prompts, enter
the two file paths printed by the helper, then press Return to omit the
provisioning profile. The helper transfers the identity through an
owner-only temporary keychain and produces a blank-password .p12 using
Apple's security export, because macOS security import rejects the
equivalent empty-password OpenSSL package on a fresh keychain. This is a
write to the private encrypted signing repository; CI always reads it.
Confirm the synced identity appears as valid in a fresh keychain; Fastlane's
generic success text alone does not prove the private key was imported.
Normal Developer ID signing for this app syncs the certificate without a
provisioning profile; the Release entitlements do not request a capability
that requires one.
The original export contains the private key: keep it owner-readable only
and remove it when read-only retrieval has been verified. If the
certificate is renewed, review the pinned fingerprint in the helper before
importing its replacement.
After import, set the variables from fastlane/.env.example in an ignored local
file or the process environment. MATCH_PASSWORD is the existing encryption
password; DESKTOP_MATCH_GIT_URL is the same private git repository as iOS.
The App Store Connect key supplies notarization authentication. Use an
explicit build number when preparing a release for review:
MACOS_BUILD_NUMBER=1 bundle exec fastlane mac release
On CI, the build number defaults to the positive GitHub run number. Inspect
the output checksum, notarization.json, metadata, and DMG. A notarization
failure, a failed Gatekeeper assessment, or a missing architecture is a
release failure; do not distribute its DMG. The local archive is rebuilt from
the current working tree, so use a reviewed commit for a release candidate.
GitHub Actions
The Crystal Lattice Desktop release workflow runs only by manual dispatch
from main. Its safe default, publish_download = false, verifies, signs,
notarizes, and stores the candidate as a seven-day workflow artifact without
making it public.
After reviewing the run's source commit, version/build, checksum, and
notarization result, dispatch again with publish_download = true and set
candidate_run_id to that successful build-only run. The publication job
verifies the referenced run is a completed successful execution of this
workflow on main, downloads that exact artifact, and sends it to the existing
private S3/CloudFront download infrastructure without rebuilding:
https://download.crystallattice.dev/crystal-lattice-desktop/
The public files are the versioned DMG and checksum, versioned release and
notarization JSON, and latest.txt. The publisher rechecks the candidate
before AWS authentication; the public smoke test downloads the DMG and
checksum, verifies SHA-256, and checks clean-source and accepted-notarization
metadata. The application repository remains private.
The workflow reuses these existing repository variables:
IOS_APPLE_TEAM_ID, IOS_MATCH_GIT_URL, and IOS_MATCH_GIT_BRANCH. It reuses
these existing repository secrets:
IOS_APP_STORE_CONNECT_KEY_ID, IOS_APP_STORE_CONNECT_ISSUER_ID,
IOS_APP_STORE_CONNECT_KEY_CONTENT, IOS_MATCH_PASSWORD, and
IOS_MATCH_GIT_PRIVATE_KEY. These values refer to the same Apple team and
private signing repository as the iOS release. The SSH deploy key is
read-only and scoped to that repository. The workflow creates a temporary
keychain and removes the keychain and deploy-key file after the run.
Publication reuses AWS_REGION, CLI_DOWNLOADS_BUCKET,
CLI_DOWNLOADS_PREFIX, CLI_DOWNLOADS_BASE_URL,
CLI_DOWNLOADS_CLOUDFRONT_DISTRIBUTION_ID, and the
CLI_DOWNLOADS_AWS_ROLE_TO_ASSUME secret. It additionally requires
DESKTOP_DOWNLOADS_PREFIX=crystal-lattice-desktop and the derived
DESKTOP_DOWNLOADS_BASE_URL. Before the first run, update the existing
CloudFormation downloads stack and OIDC role as documented in
deploy/aws-desktop-downloads/README.md.
GitHub Free on this private repository does not provide a required-reviewer
gate for this release. The workflow has no push or pull-request trigger, runs
only on main, keeps checkout credentials out of the working tree, and grants
AWS OIDC only to the optional publication job. Human approval is represented
by deliberately dispatching with publish_download = true. Website
publication remains separate.
To recover from a failed candidate, inspect the Fastlane log and Apple's
notarization.json, repair the cause in source or signing configuration,
then run the workflow again. Do not overwrite existing release assets. To
rotate the signing identity, perform the Account Holder certificate step
locally, import into the private match repository, and verify a read-only
build before removing the previous identity. To rotate an API or deploy key,
replace the existing iOS repository secret through GitHub's secure interface,
run the desktop build-only mode, and retire the old key only after a
successful build. The iOS workflow shares those credentials, so verify it
after rotation as well.