Automated Release System - ahzs645/WhisperDesk GitHub Wiki

WhisperDesk Enhanced utilizes GitHub Actions to automate the process of building, testing, and releasing optimized versions of the application for multiple platforms. This ensures consistency and reliability in our releases.

Overview of the CI/CD Pipeline

The primary workflow is defined in .github/workflows/main.yml. Here's what the automated system does:

1. Trigger:

   • Workflows are triggered on pushes to specific branches (main, master, release).
   • Tagging a commit (e.g., v2.1.0) triggers a release workflow.
   • Pull requests to the main branch trigger build and test workflows.
   • Manual workflow dispatch with optional release creation.

2. Version Determination:

   • For tagged releases: Extracts version from git tag and updates package.json
   • For manual releases: Uses provided release tag input
   • For development builds: Uses current package.json version with -dev suffix

3. Multi-Platform Build Matrix:

   • Windows: x64 architecture with Release build type
   • macOS: Both x64 (Intel) and arm64 (Apple Silicon) architectures
   • Linux: x64 architecture with Ubuntu 22.04 base

4. Setup Environment:

   • Node.js 20 with npm caching
   • pnpm for renderer dependencies
   • Platform-specific build tools (MSBuild for Windows, cmake for all platforms)

5. Checkout Code:

   • Fetches the latest code from the repository with full history for version determination

6. Install Dependencies:

   • Main application: npm install with script ignoring for CI
   • Renderer UI: pnpm install --frozen-lockfile in src/renderer/whisperdesk-ui
   • Version synchronization across all package.json files

7. Build Native Components (whisper.cpp):

   • Windows: Official whisper.cpp build method using CMake
     • Fetches SDL2 development libraries
     • Builds with shared libraries enabled (BUILD_SHARED_LIBS=ON)
     • Compiles whisper-cli.exe (updated from deprecated main.exe)
     • Includes all required DLLs: whisper.dll, ggml.dll, ggml-base.dll, ggml-cpu.dll, SDL2.dll
     • Optional executables: whisper-stream.exe, whisper-server.exe, whisper-bench.exe, quantize.exe
   • macOS/Linux: Uses npm run build:whisper script for platform-specific compilation

8. Model Download:

   • Downloads ggml-tiny.bin model from Hugging Face for testing and bundling

9. Binary Testing:

   • Verifies all required files exist
   • Tests whisper-cli.exe execution (non-blocking on exit codes)
   • Validates file sizes and integrity

10. Build Renderer UI:

    • Compiles the React-based UI using pnpm run build
    • Located in src/renderer/whisperdesk-ui/dist

11. Package Application (Electron Builder):

    • Windows:
      • NSIS installer (.exe)
      • ZIP archive (renamed to "Portable" version)
    • macOS:
      • ZIP archives for both Intel and Apple Silicon
    • Linux:
      • AppImage (portable)
      • Debian package (.deb)
      • RPM package (.rpm)
      • Generic tar.gz archive

12. Portable Version Handling:

    • Runs scripts/rename-portable.js to rename ZIP files to "Portable" versions
    • Ensures true portability without installation requirements

13. Artifact Upload:

    • Platform-specific artifacts with 30-day retention
    • Organized by platform and architecture

14. Release Creation:

    • Triggered for tagged releases, manual releases, or development builds
    • Downloads all build artifacts
    • Creates GitHub Release with comprehensive description
    • Includes platform-specific download instructions

Release Types & Strategy

• Stable Releases:

  • Triggered by version tags (e.g., v2.1.0)
  • Full platform matrix builds
  • Published as non-draft, non-prerelease
  • Comprehensive release notes with download instructions

• Manual Releases:

  • Triggered via workflow dispatch with create_release: true
  • Allows custom release tag specification
  • Same build quality as stable releases

• Development Builds:

  • Triggered by pushes to main branches
  • Version suffixed with -dev
  • Marked as prerelease
  • Useful for testing latest changes

Technical Implementation Details

Build Environment Configuration

• Concurrency: Prevents duplicate runs using branch/run ID grouping
• Permissions: Comprehensive access for contents, actions, checks, and pull requests
• Node.js: Version 20 with npm caching across all platforms

Windows-Specific Build Process

strategy:
  matrix:
    arch: [x64]
    build_type: [Release]
    sdl2: [ON]

• Uses official whisper.cpp CMake configuration
• Builds with examples and server components
• Implements proper DLL handling for distribution
• SDL2 integration for enhanced audio processing

Version Management

• Synchronizes versions across main and renderer package.json files
• Supports semantic versioning with development suffixes
• Automatic package.json updates during build process

Quality Assurance

• Binary verification before packaging
• Model download validation
• Prerequisite checking at each build stage
• Error handling with detailed logging

Release Artifacts

Each release includes:

• Windows: Setup installer + Portable ZIP
• macOS: Separate builds for Intel and Apple Silicon
• Linux: Multiple package formats for different distributions

File Structure Requirements

The automated system expects:

• package.json in root directory
• src/renderer/whisperdesk-ui/ for renderer components
• binaries/ directory for whisper.cpp executables
• models/ directory for AI models
• scripts/rename-portable.js for post-build processing

Troubleshooting

Common Build Issues

• Missing DLLs: Ensure all whisper.cpp dependencies are built and copied
• Binary Testing Failures: whisper-cli.exe may exit with non-zero codes normally
• Model Download: Network issues may require retry mechanisms
• Version Synchronization: Ensure all package.json files are updated consistently

This automated system eliminates manual release procedures and ensures consistent, high-quality builds across all supported platforms while leveraging the latest whisper.cpp implementations.