Skip to main content
This page is for Sparkles maintainers shipping the CLI and its documentation.

​
Current v1.3.0 channels

The signed build identifies commit ead2e9b06711a50b0920cc379f69f8133bb0bc67. The release assets are available from GitHub release v1.3.0.

​
Automated release sequence

  1. Merge Conventional Commits into the CLI repository’s main branch.
  2. Merge the Release Please pull request to create the version tag and GitHub release.
  3. Build all platform archives.
  4. Sign and notarize both macOS architectures before creating the immutable release bundle.
  5. Publish the exact bundle to GitHub Releases and versioned Cloudflare R2 paths.
  6. Publish the npm platform packages and shim under a staging tag.
  7. Update Homebrew.
  8. Move npm latest and the stable installer pointer only after every channel succeeds.
Never publish the npm shim before its platform packages. npm versions are immutable, so an unsigned or incomplete package must be replaced by a new version rather than overwritten.

​
GitHub release environment

The CLI repository uses the GitHub environment named release.

​
Secrets

  • AWS_ACCESS_KEY_ID
  • AWS_SECRET_ACCESS_KEY
  • MACOS_SIGN_P12
  • MACOS_SIGN_PASSWORD
  • MACOS_NOTARY_KEY
  • MACOS_NOTARY_KEY_ID
  • MACOS_NOTARY_ISSUER_ID
  • NPM_TOKEN
  • HOMEBREW_TAP_TOKEN

​
Variables

  • AWS_ENDPOINT_URL
  • R2_BUCKET
Create the R2 S3 credentials in Cloudflare under R2 object storage → Manage API Tokens. Grant Object Read & Write access only to the release bucket, then copy the one-time Access Key ID and Secret Access Key into the AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY secrets. Cloudflare shows an account-specific S3 endpoint alongside those credentials; copy it into the AWS_ENDPOINT_URL variable, and set R2_BUCKET to the release bucket name. See Cloudflare’s S3 credential guide.

​
Recover a failed release

Use GitHub’s failed-job retry while the original workflow still has its artifacts. If a full rerun loses the artifact, dispatch the Release workflow with the existing v* tag so it can recover from the immutable signed bundle attached to the release. If signing and notarization pass but publication fails:
  1. Download the release bundle artifact.
  2. Verify every archive against checksums.txt.
  3. Extract both macOS archives and verify each extracted binary by path, such as codesign --verify --deep --strict ./sparkles. codesign requires an explicit target and fails when it is omitted.
  4. Publish the same bytes to the GitHub release and versioned R2 path.
  5. Download the public objects and compare them with the bundle before moving the stable pointer.
A local Wrangler login can recover an individual release, but it does not replace AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY in GitHub Actions. Add the S3 credentials so the next release completes automatically.

​
Protect and rotate Apple credentials

Never send .p12 certificates, .p8 keys, or export passwords through chat, tickets, source control, or documentation. Put them directly into the GitHub release environment. If an App Store Connect API key is exposed, revoke it and create a replacement. Apple recommends revoking lost or compromised keys immediately. See Revoking API keys. Treat a possible Developer ID key compromise as an incident rather than a rotation. If a private key or an exported .p12 may have reached anyone outside the release owners, remove its CI access immediately by deleting MACOS_SIGN_P12 and MACOS_SIGN_PASSWORD from the release environment, and contact Apple Product Security right away: whoever holds that identity can distribute software as Sparkles until it is revoked. Revocation blocks installation and launch of every build already signed with that certificate, so tell users which versions stop working and create, sign, and ship the replacement release in parallel instead of waiting for it before acting. For routine rotation of a certificate that is not compromised, do not revoke it before a replacement-signed release is live. Apple states that software signed with a revoked Developer ID certificate can no longer be installed or launched. Create a replacement certificate, update the GitHub signing secrets, ship a new release, and then contact Apple about revoking the old certificate. See Revoking Developer ID privileges.

​
Deploy the Mintlify docs

The Mintlify project root is docs/api. Validate changes from the application repository root:
The Mintlify GitHub integration watches /docs/api and deploys changes after they merge into main. A docs-only change does not require bun run deploy, a Cloudflare Worker deployment, or a CLI release.