How to Update PI-Desktop: The Official Release Workflow Explained

To update PI-Desktop, contributors run the scripts/release.mjs driver after validating version alignment with scripts/check-release-docs.mjs, which triggers CI to build, sign, and publish signed artifacts for macOS, Linux, and Windows.

The update process for PI-Desktop is governed by a rigorous, script-driven workflow defined in the vastsa/PI-Desktop repository. This system ensures version consistency across bilingual documentation, Rust core constants, and Node.js workspaces while guaranteeing that every distributed binary is signed, notarized, and cryptographically verified. Understanding how to update PI-Desktop requires familiarity with the automation scripts in scripts/ and the CI pipeline defined in .github/workflows/release.yml.

The Six-Stage Update Pipeline

The release process is orchestrated by shell and Node.js scripts located in the repository’s scripts/ directory, with formal specifications documented in docs/spec/06-delivery/06-release-runbook.md. Each stage gates the next, preventing version drift or unsigned artifacts from reaching users.

1. Prepare the Version Bump

Before any Git tag is created, every version surface must be synchronized. This validation is enforced by scripts/check-release-docs.mjs, which scans:

• The bilingual changelog in packages/shared/src/changelog.ts
• All workspace package.json files and the Cargo workspace version
• The APP_VERSION constant in the Rust host core
• Version strings in README.md and README.zh-CN.md

If any surface is out-of-sync, the script exits with a non-zero code and blocks the release. Run this check manually with:

pnpm check:release-docs

2. Execute the Release Driver

Once documentation passes validation, invoke the main release driver:

node scripts/release.mjs 1.2.3 --tag

The scripts/release.mjs script performs atomic version bumps across the monorepo:

1. Updates every workspace package.json and the Cargo manifest
2. Synchronizes APP_VERSION inside crates/host-core/src/lib.rs
3. Re-runs scripts/check-release-docs.mjs to detect post-bump drift
4. Commits changes and creates a signed Git tag (vX.Y.Z) when --tag is supplied

If the documentation check fails at this stage, the script aborts and no tag is created.

3. Build Cross-Platform Artifacts

After a signed tag exists, the release workflow in .github/workflows/release.yml automatically triggers. It executes a build matrix for macOS, Linux, and Windows using platform-specific scripts:

• macOS: scripts/release-macos.sh builds a notarized DMG and signs binaries with the Developer ID
• Linux: scripts/export-linux-asar.mjs extracts the app.asar for distribution packaging
• Windows: The release script generates an NSIS installer and optional portable executable

4. Validate Signed Binaries

For macOS, scripts/verify-macos-release.sh performs cryptographic verification:

scripts/verify-macos-release.sh apps/desktop/release/mac-x64/PI-Desktop.app

This script confirms that the .app bundle and DMG are correctly signed, notarized, and stapled. Linux and Windows artifacts undergo checksum validation and smoke-testing in CI before publication.

5. Publish to GitHub

The workflow uses softprops/action-gh-release to create a GitHub Release entry. It automatically populates release notes from packages/shared/src/changelog.ts and attaches the verified build assets. This step represents the final public distribution point for the update.

6. Post-Release Housekeeping

After a successful release, maintainers update the CHANGELOG files and refresh README documentation to reflect the current stable line. Development continues on feature branches, keeping the main branch synchronized with the latest release tag.

Local Testing Commands

Before triggering a full release, you can test the build pipeline locally:

# Build the Rust host core in release mode

pnpm build:host-release

# Build the Electron renderer

pnpm build:desktop

# Verify macOS artifacts locally (requires built app)

scripts/verify-macos-release.sh apps/desktop/release/mac-x64/PI-Desktop.app

Summary

• Safety First: The check-release-docs.mjs script gates every release, preventing version mismatches between Rust, Node.js, and documentation files.
• Atomic Bumps: scripts/release.mjs updates all version surfaces in a single commit and optionally creates a signed Git tag.
• Secure Artifacts: macOS binaries are notarized and stapled, while Linux and Windows builds are checksum-verified before publication.
• Traceability: The entire process is documented in docs/spec/06-delivery/06-release-runbook.md, enabling reproducible releases.

Frequently Asked Questions

What files must be updated before I can create a new PI-Desktop release?

You must synchronize packages/shared/src/changelog.ts, all workspace package.json files, the Cargo.toml workspace version, the APP_VERSION constant in the Rust host core, and both README.md and README.zh-CN.md. The scripts/check-release-docs.mjs script validates that all these surfaces match.

How do I create a signed Git tag for the release?

Run node scripts/release.mjs <new-version> --tag from the repository root. This bumps all version strings, commits the changes, and creates a signed Git tag in the format vX.Y.Z. If the documentation check fails, the script exits before creating the tag.

Where are the macOS signing and notarization scripts located?

The macOS-specific build logic resides in scripts/release-macos.sh, which produces the notarized DMG and signed application bundle. Verification is handled by scripts/verify-macos-release.sh, which confirms proper code signing and stapling.

Can I run the release build process locally without publishing?

Yes. You can build the Rust host core with pnpm build:host-release and the Electron renderer with pnpm build:desktop. For macOS, you can then run scripts/verify-macos-release.sh against the local build artifacts to validate signing, though notarization requires Apple Developer credentials configured in CI.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}