CI/CD & Build Pipeline
Relevant source files
The following files were used as context for generating this wiki page:
The mausVoice project utilizes a comprehensive CI/CD and build pipeline to manage its multi-platform desktop application. The pipeline is designed to handle a Turborepo monorepo structure, coordinating builds for macOS, Windows, and Linux. It encompasses automated testing, linting, cross-platform compilation via Tauri v2, and a multi-channel release strategy.
The system relies on GitHub Actions for automation, utilizing specific workflow templates stored in personal-fork-ci/ to ensure CI stability even if live workflows drift. The pipeline orchestrates complex native dependencies, including Rust toolchains for the core API and TypeScript/React for the application logic.
Pipeline Architecture & Workflows
The CI/CD architecture is split into validation gates (Build Desktop, Lint Desktop) and a dedicated release pipeline. Validation occurs on pull requests to main and linting branches for specific paths like apps/desktop/**.
Build Strategy Matrix
The build pipeline employs a GitHub Actions matrix to handle platform-specific requirements simultaneously. This includes varying operating systems, Rust targets, and environment configurations.
Note: The pipeline builds universal binaries for macOS and standard installers for Windows.
Sources: personal-fork-ci/workflows/build-desktop.yml:13-35, personal-fork-ci/APPLY.md:8-11
Key Build Jobs and Definitions
| Component | Description |
|---|---|
| build-desktop.yml | The primary CI gate for desktop builds across platforms. |
| lint-desktop.yml | Handles linting for the desktop app and the three native "pill" crates. |
| release.yml | A single workflow_dispatch based pipeline for production releases. |
| setup-macos.sh | Local environment script for satisfying macOS build prerequisites. |
Sources: personal-fork-ci/APPLY.md:8-15, scripts/setup-macos.sh
Desktop Build Process
The build process for the desktop application is a hybrid routine involving Node.js/pnpm for the frontend and Cargo/Rust for the native Tauri shell and sidecars.
Step-by-Step Execution
- Environment Setup: Standardizes Node.js (via
.nvmrc), Bun (v1.3.6), and Rust stable toolchains. - Dependency Management: Uses
pnpm install --frozen-lockfileto ensure deterministic builds. - Frontend Compilation: Executes
turbo run build --filter=desktop...to build the React frontend and its local workspace dependencies. - Tauri Build: The Rust-based Tauri CLI bundles the application. On macOS, this includes adding targets for both
aarch64andx86_64to create a universal binary. - Sidecar Integration: Specific toolchain files are injected via
CMAKE_TOOLCHAIN_FILEto build native transcription sidecars.
Sources: personal-fork-ci/workflows/build-desktop.yml:37-95, apps/desktop/package.json:7-20
Security and Signing in CI
For CI validation builds, the pipeline uses a "throwaway" signing key (TAURI_SIGNING_PRIVATE_KEY) and a corresponding public key for the updater plugin. Real production releases utilize protected secrets within the release.yml workflow.
Note: The build process dynamically patches the configuration to enable updater testing during CI.
Sources: personal-fork-ci/workflows/build-desktop.yml:95-125
Release & Deployment Pipeline
The release pipeline follows a multi-channel strategy based on branch promotion.
Release Channels
| Branch | Channel | Target Components |
|---|---|---|
main | dev | Desktop, Enterprise-dev, Gateway |
prod | prod | Desktop, Docs |
enterprise | enterprise | Desktop, Admin, Gateway |
Sources: release/README.md:3-9
Promotion Flow
Releases are triggered by pushing to or merging into the respective channel branches. A promotion PR (e.g., main → prod) allows for diff review before the automated release triggers.
Sources: release/README.md:16-25
Homebrew Tap Integration
The macOS release process includes an automated job to update the Homebrew tap:
- SHA-256 Computation: After the DMG is built, its checksum is calculated.
- Cask Rendering: The
render-cask.mjsscript updates the version, tag, and SHA-256 in the Homebrew formula. - Automated Commit: The updated cask is pushed to the
maus-inc/homebrew-mausvoicerepository.
Sources: homebrew-mausvoice/README.md:21-30
Setup and Quality Scripts
To maintain build quality and developer environment parity, the project includes several scripts for local and CI use.
macOS Local Setup
The scripts/setup-macos.sh script automates the installation of:
- Xcode Command Line Tools: Required for
clang. - Homebrew Dependencies:
cmake(for whisper-rs) andpkg-config. - Language Runtimes: Node.js (v18+),
pnpm(via corepack), and Rust (viarustup).
Sources: scripts/setup-macos.sh:19-115
Quality Commands
Standardized scripts in the monorepo root and apps/desktop:
pnpm run build: Orchestrates Turborepo to build all workspaces.pnpm run lint: Runs Prettier and oxlint.pnpm run check-types: Executestsc --noEmit.pnpm run test: Runs Vitest unit and integration tests.
Sources: README.md:129-136, apps/desktop/package.json:20-28
The mausVoice CI/CD pipeline ensures that complex native Rust code and React frontend logic are consistently validated and deployed across three major operating systems, upholding a high standard of quality through strictly controlled build environments and automated release channels.