From c04d2cb226e4592260d865efd3fec24aa0a831fe Mon Sep 17 00:00:00 2001 From: Ammar Date: Sun, 16 Nov 2025 17:21:18 -0600 Subject: [PATCH] ci/docs: add reusable packages workflow and mux server docs --- .github/workflows/build.yml | 102 +--------------- .github/workflows/packages.yml | 216 +++++++++++++++++++++++++++++++++ .github/workflows/release.yml | 111 ++--------------- docs/install.md | 21 +++- 4 files changed, 249 insertions(+), 201 deletions(-) create mode 100644 .github/workflows/packages.yml diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index 3c0dff683..2332c18f6 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -7,99 +7,9 @@ on: workflow_dispatch: # Allow manual triggering jobs: - build-macos: - name: Build macOS - runs-on: ${{ github.repository_owner == 'coder' && 'depot-macos-15' || 'macos-latest' }} - steps: - - name: Checkout code - uses: actions/checkout@v4 - with: - fetch-depth: 0 # Required for git describe to find tags - - - uses: ./.github/actions/setup-mux - - - name: Setup code signing - run: ./scripts/setup-macos-signing.sh - env: - MACOS_CERTIFICATE: ${{ secrets.MACOS_CERTIFICATE }} - MACOS_CERTIFICATE_PWD: ${{ secrets.MACOS_CERTIFICATE_PWD }} - AC_APIKEY_P8_BASE64: ${{ secrets.AC_APIKEY_P8_BASE64 }} - AC_APIKEY_ID: ${{ secrets.AC_APIKEY_ID }} - AC_APIKEY_ISSUER_ID: ${{ secrets.AC_APIKEY_ISSUER_ID }} - - - name: Verify signing setup - run: | - if [ -n "${CSC_LINK:-}" ]; then - echo "✅ Code signing enabled" - security list-keychains -d user - security find-identity -v -p codesigning - else - echo "⚠️ Code signing NOT enabled" - fi - - - name: Package for macOS - run: make dist-mac - env: - CSC_FOR_PULL_REQUEST: ${{ github.event.pull_request.number == 234 }} - - - name: Upload macOS DMG (x64) - uses: actions/upload-artifact@v4 - with: - name: macos-dmg-x64 - path: release/*-x64.dmg - retention-days: 30 - if-no-files-found: error - - - name: Upload macOS DMG (arm64) - uses: actions/upload-artifact@v4 - with: - name: macos-dmg-arm64 - path: release/*-arm64.dmg - retention-days: 30 - if-no-files-found: error - - build-linux: - name: Build Linux - runs-on: ${{ github.repository_owner == 'coder' && 'depot-ubuntu-22.04-16' || 'ubuntu-latest' }} - steps: - - name: Checkout code - uses: actions/checkout@v4 - with: - fetch-depth: 0 # Required for git describe to find tags - - - uses: ./.github/actions/setup-mux - - - name: Build application - run: bun run build - - - name: Package for Linux - run: make dist-linux - - - name: Upload Linux AppImage - uses: actions/upload-artifact@v4 - with: - name: linux-appimage - path: release/*.AppImage - retention-days: 30 - if-no-files-found: error - - build-vscode-extension: - name: Build VS Code Extension - runs-on: ${{ github.repository_owner == 'coder' && 'depot-ubuntu-22.04-16' || 'ubuntu-latest' }} - steps: - - name: Checkout code - uses: actions/checkout@v4 - with: - fetch-depth: 0 # Required for git describe to find tags - - - uses: ./.github/actions/setup-mux - - - uses: ./.github/actions/build-vscode-extension - - - name: Upload VS Code extension artifact - uses: actions/upload-artifact@v4 - with: - name: vscode-extension - path: vscode/mux-*.vsix - retention-days: 30 - if-no-files-found: error + build-artifacts: + name: Build desktop + extension artifacts + uses: ./.github/workflows/packages.yml + with: + mode: build + secrets: inherit diff --git a/.github/workflows/packages.yml b/.github/workflows/packages.yml new file mode 100644 index 000000000..d01b0817b --- /dev/null +++ b/.github/workflows/packages.yml @@ -0,0 +1,216 @@ +name: Build Artifacts + +on: + workflow_call: + inputs: + mode: + description: 'Set to "build" for CI artifacts or "release" for signed releases.' + required: true + type: string + release_tag: + description: 'Release tag name (required when mode == release)' + required: false + type: string + secrets: + MACOS_CERTIFICATE: + required: false + MACOS_CERTIFICATE_PWD: + required: false + AC_APIKEY_P8_BASE64: + required: false + AC_APIKEY_ID: + required: false + AC_APIKEY_ISSUER_ID: + required: false + GH_TOKEN: + required: false + VSCE_PAT: + required: false + +jobs: + macos: + name: ${{ inputs.mode == 'release' && 'Build and Release macOS' || 'Build macOS' }} + runs-on: ${{ github.repository_owner == 'coder' && 'depot-macos-15' || 'macos-latest' }} + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 + + - uses: ./.github/actions/setup-mux + + - name: Setup code signing + run: ./scripts/setup-macos-signing.sh + env: + MACOS_CERTIFICATE: ${{ secrets.MACOS_CERTIFICATE }} + MACOS_CERTIFICATE_PWD: ${{ secrets.MACOS_CERTIFICATE_PWD }} + AC_APIKEY_P8_BASE64: ${{ secrets.AC_APIKEY_P8_BASE64 }} + AC_APIKEY_ID: ${{ secrets.AC_APIKEY_ID }} + AC_APIKEY_ISSUER_ID: ${{ secrets.AC_APIKEY_ISSUER_ID }} + + - name: Verify signing setup + if: inputs.mode == 'build' + run: | + if [ -n "${CSC_LINK:-}" ]; then + echo "✅ Code signing enabled" + security list-keychains -d user + security find-identity -v -p codesigning + else + echo "⚠️ Code signing NOT enabled" + fi + + - name: Build application + run: bun run build + + - name: Package for macOS + if: inputs.mode == 'build' + run: make dist-mac + env: + CSC_FOR_PULL_REQUEST: ${{ github.event.pull_request && github.event.pull_request.number == 234 }} + + - name: Package and publish for macOS + if: inputs.mode == 'release' + run: make dist-mac-release + env: + GH_TOKEN: ${{ secrets.GH_TOKEN }} + + - name: Upload macOS DMG (x64) + if: inputs.mode == 'build' + uses: actions/upload-artifact@v4 + with: + name: macos-dmg-x64 + path: release/*-x64.dmg + retention-days: 30 + if-no-files-found: error + + - name: Upload macOS DMG (arm64) + if: inputs.mode == 'build' + uses: actions/upload-artifact@v4 + with: + name: macos-dmg-arm64 + path: release/*-arm64.dmg + retention-days: 30 + if-no-files-found: error + + linux: + name: ${{ inputs.mode == 'release' && 'Build and Release Linux' || 'Build Linux' }} + runs-on: ${{ github.repository_owner == 'coder' && 'depot-ubuntu-22.04-16' || 'ubuntu-latest' }} + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 + + - uses: ./.github/actions/setup-mux + + - name: Build application + run: bun run build + + - name: Package for Linux + if: inputs.mode == 'build' + run: make dist-linux + + - name: Package and publish for Linux + if: inputs.mode == 'release' + run: bun x electron-builder --linux --publish always + env: + GH_TOKEN: ${{ secrets.GH_TOKEN }} + + - name: Upload Linux AppImage + if: inputs.mode == 'build' + uses: actions/upload-artifact@v4 + with: + name: linux-appimage + path: release/*.AppImage + retention-days: 30 + if-no-files-found: error + + windows: + name: ${{ inputs.mode == 'release' && 'Build and Release Windows' || 'Build Windows' }} + runs-on: windows-latest + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 + + - uses: ./.github/actions/setup-mux + + - name: Install GNU Make + shell: powershell + run: choco install -y make + + - name: Verify tools + shell: bash + run: | + make --version + bun --version + magick --version | head -1 + + - name: Build application + shell: pwsh + run: bun run build + + - name: Package for Windows (.exe) + if: inputs.mode == 'build' + shell: pwsh + run: make dist-win + + - name: Package and publish for Windows (.exe) + if: inputs.mode == 'release' + shell: pwsh + run: bun x electron-builder --win --publish always + env: + GH_TOKEN: ${{ secrets.GH_TOKEN }} + + - name: Upload Windows installer (.exe) + if: inputs.mode == 'build' + uses: actions/upload-artifact@v4 + with: + name: windows-installer + path: release/*.exe + retention-days: 30 + if-no-files-found: error + + vscode-extension: + name: ${{ inputs.mode == 'release' && 'Build and Publish VS Code Extension' || 'Build VS Code Extension' }} + runs-on: ${{ github.repository_owner == 'coder' && 'depot-ubuntu-22.04-16' || 'ubuntu-latest' }} + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 + + - uses: ./.github/actions/setup-mux + + - uses: ./.github/actions/build-vscode-extension + + - name: Upload VS Code extension artifact + if: inputs.mode == 'build' + uses: actions/upload-artifact@v4 + with: + name: vscode-extension + path: vscode/mux-*.vsix + retention-days: 30 + if-no-files-found: error + + - name: Upload VS Code extension to release + if: inputs.mode == 'release' + env: + GH_TOKEN: ${{ secrets.GH_TOKEN }} + run: | + if [ -z "${{ inputs.release_tag }}" ]; then + echo "release_tag input is required when publishing" + exit 1 + fi + gh release upload "${{ inputs.release_tag }}" \ + vscode/mux-*.vsix \ + --clobber + + - name: Publish to VS Code Marketplace + if: inputs.mode == 'release' + working-directory: vscode + env: + VSCE_PAT: ${{ secrets.VSCE_PAT }} + run: | + if [ -z "${VSCE_PAT:-}" ]; then + echo "VSCE_PAT not set; skipping Marketplace publish." + exit 0 + fi + bunx vsce publish -p $VSCE_PAT diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 3d4747819..e9d6c4bc7 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -8,107 +8,10 @@ permissions: contents: write # Required for electron-builder to upload release assets jobs: - build-macos: - name: Build and Release macOS - runs-on: ${{ github.repository_owner == 'coder' && 'depot-macos-15' || 'macos-latest' }} - steps: - - name: Checkout code - uses: actions/checkout@v4 - with: - fetch-depth: 0 # Required for git describe to find tags - - - uses: ./.github/actions/setup-mux - - - name: Build application - run: bun run build - - - name: Setup code signing - run: ./scripts/setup-macos-signing.sh - env: - MACOS_CERTIFICATE: ${{ secrets.MACOS_CERTIFICATE }} - MACOS_CERTIFICATE_PWD: ${{ secrets.MACOS_CERTIFICATE_PWD }} - AC_APIKEY_P8_BASE64: ${{ secrets.AC_APIKEY_P8_BASE64 }} - AC_APIKEY_ID: ${{ secrets.AC_APIKEY_ID }} - AC_APIKEY_ISSUER_ID: ${{ secrets.AC_APIKEY_ISSUER_ID }} - - - name: Package and publish for macOS - run: make dist-mac-release - env: - GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} - - build-linux: - name: Build and Release Linux - runs-on: ${{ github.repository_owner == 'coder' && 'depot-ubuntu-22.04-16' || 'ubuntu-latest' }} - steps: - - name: Checkout code - uses: actions/checkout@v4 - with: - fetch-depth: 0 # Required for git describe to find tags - - - uses: ./.github/actions/setup-mux - - - name: Build application - run: bun run build - - - name: Package and publish for Linux - run: bun x electron-builder --linux --publish always - env: - GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} - - build-vscode-extension: - name: Build and Release VS Code Extension - runs-on: ${{ github.repository_owner == 'coder' && 'depot-ubuntu-22.04-16' || 'ubuntu-latest' }} - steps: - - name: Checkout code - uses: actions/checkout@v4 - with: - fetch-depth: 0 # Required for git describe to find tags - - - uses: ./.github/actions/setup-mux - - - uses: ./.github/actions/build-vscode-extension - - - name: Upload VS Code extension to release - env: - GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} - run: | - gh release upload ${{ github.event.release.tag_name }} \ - vscode/mux-*.vsix \ - --clobber - - - name: Publish to VS Code Marketplace - if: secrets.VSCE_PAT != '' - working-directory: vscode - env: - VSCE_PAT: ${{ secrets.VSCE_PAT }} - run: | - bunx vsce publish -p $VSCE_PAT - - build-windows: - name: Build and Release Windows - runs-on: windows-latest - steps: - - name: Checkout code - uses: actions/checkout@v4 - with: - fetch-depth: 0 # Required for git describe to find tags - - - uses: ./.github/actions/setup-mux - - - name: Install GNU Make (for build) - run: choco install -y make - - - name: Verify tools - shell: bash - run: | - make --version - bun --version - magick --version | head -1 - - - name: Build application - run: bun run build - - - name: Package and publish for Windows (.exe) - run: bun x electron-builder --win --publish always - env: - GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + publish-artifacts: + name: Release desktop + extension artifacts + uses: ./.github/workflows/packages.yml + with: + mode: release + release_tag: ${{ github.event.release.tag_name }} + secrets: inherit diff --git a/docs/install.md b/docs/install.md index 9f7223527..c7c3876f7 100644 --- a/docs/install.md +++ b/docs/install.md @@ -8,15 +8,17 @@ Download pre-built binaries from [the releases page](https://github.com/coder/mu - **macOS**: Signed and notarized DMG (separate builds for Intel/Apple Silicon) - **Linux**: AppImage +- **Windows**: Signed installer (.exe) ### Development Builds -Down pre-built binaries of `main` from [GitHub Actions](https://github.com/coder/mux/actions/workflows/build.yml): +Download pre-built binaries of `main` from [GitHub Actions](https://github.com/coder/mux/actions/workflows/build.yml): - **macOS**: Signed and notarized DMG - `macos-dmg-x64` (Intel Macs) - `macos-dmg-arm64` (Apple Silicon) - **Linux**: AppImage (portable, works on most distros) +- **Windows**: Installer (.exe) – artifact `windows-installer` To download: @@ -38,12 +40,29 @@ To download: The app is code-signed and notarized by Apple, so it will open without security warnings. +**Windows:** + +1. Download the `.exe` installer from the release page or the `windows-installer` artifact. +2. Double-click the installer and follow the prompts. The installer places Mux in `%LOCALAPPDATA%\Programs\mux` and adds a Start Menu entry. +3. If SmartScreen warns about the binary (common for unsigned preview builds), click **More info** → **Run anyway**. +4. Launch Mux from the Start Menu or run `mux.exe --server` from PowerShell to start the browser-accessible server mode directly. + **Linux:** 1. Download the AppImage file 2. Make it executable: `chmod +x Mux-*.AppImage` 3. Run it: `./Mux-*.AppImage` +### Running Mux in server mode + +Mux includes a lightweight server mode so you can keep the agent running without the desktop shell and reach it from any browser (desktop, tablet, or phone). After installing, run `mux --server` (or `mux.exe --server` on Windows) to start an HTTP/WebSocket control plane. + +- The server hosts the full Mux UI over the web and prints a URL such as `http://localhost:3000`. Open that URL from the same machine, or expose it via a tunnel/VPN to reach it from mobile devices. +- Use `--host 0.0.0.0` to bind to all interfaces and `--port ` to pick a different port. +- Pass `--add-project /path/to/repo` to register and auto-open a workspace when the browser connects. + +This mode is ideal for mobile development: keep the heavy Electron app on a workstation, run `mux --server`, and interact with the session from your phone or tablet browser. + ### Testing Pre-Release Builds ⚠️ **Note**: Only builds from the `main` branch are signed and notarized. If you're testing a build from a pull request or other branch, you'll need to bypass macOS Gatekeeper: