Guide: Building latest Windows x64 installer (.exe / .msi) on a fork via GitHub Actions

[ham-zax]

Overview

For Windows users who want to build and test the latest development code from the upstream main branch into a working Windows installer (.exe or .msi) without setting up complex local toolchains (Zig, CGO, Go, Node, Task) and without maintainer code-signing credentials, here is a verified step-by-step workflow using GitHub Actions on your fork.

---

Step-by-Step Instructions

1. Fork and Sync

1. Fork wavetermdev/waveterm to your GitHub account.
2. Ensure your fork's main branch is synced with the latest upstream main commit.

2. Configure GitHub Actions Workflow

In your fork, update .github/workflows/build-helper.yml to target Windows x64 only and run unsigned:

name: Build Helper
run-name: Build Windows x64 ${{ github.ref_name }}${{ github.event_name == 'workflow_dispatch' && ' - Manual' || '' }}
on:
    workflow_dispatch:

env:
    NODE_VERSION: 22
    NODE_OPTIONS: --max-old-space-size=4096

jobs:
    build-app:
        runs-on: windows-latest
        steps:
            - uses: actions/checkout@v6

            - name: Install Zig
              uses: mlugg/setup-zig@v2

            - uses: actions/setup-go@v6
              with:
                  go-version-file: go.mod
                  cache-dependency-path: |
                      go.sum

            - uses: actions/setup-node@v6
              with:
                  node-version: ${{ env.NODE_VERSION }}
                  cache: npm
                  cache-dependency-path: package-lock.json

            - name: Force git deps to HTTPS
              run: |
                  git config --global url.https://github.com/.insteadof ssh://git@github.com/
                  git config --global url.https://github.com/.insteadof git@github.com:

            - uses: nick-fields/retry@v4
              name: npm ci
              with:
                  command: npm ci --no-audit --no-fund
                  retry_on: error
                  max_attempts: 3
                  timeout_minutes: 5
              env:
                  GIT_ASKPASS: "echo"
                  GIT_TERMINAL_PROMPT: "0"

            - name: Install Task
              uses: arduino/setup-task@v2
              with:
                  version: 3.x
                  repo-token: ${{ secrets.GITHUB_TOKEN }}

            - name: "Set Version"
              id: set-version
              run: echo "WAVETERM_VERSION=$(task version)" >> "$GITHUB_OUTPUT"
              shell: bash

            - name: Build (Windows)
              run: task package
              env:
                  CSC_IDENTITY_AUTO_DISCOVERY: "false"
              shell: powershell

            - name: Verify Windows Installer
              id: verify-installer
              shell: powershell
              run: |
                  $installers = Get-ChildItem -Path make -Include *.exe, *.msi -Recurse -File
                  if (-not $installers) {
                      Write-Error "No Windows installer (.exe or .msi) was generated in make/!"
                      exit 1
                  }
                  Write-Host "Found Windows installer(s):"
                  foreach ($inst in $installers) {
                      $hash = (Get-FileHash -Path $inst.FullName -Algorithm SHA256).Hash
                      Write-Host "  Name: $($inst.Name)"
                      Write-Host "  Size: $($inst.Length) bytes"
                      Write-Host "  SHA256: $hash"
                  }

            - name: Upload Windows Installer Artifact
              uses: actions/upload-artifact@v4
              with:
                  name: wave-windows-x64-installer
                  path: |
                      make/*.exe
                      make/*.msi
                      make/*.zip
                  if-no-files-found: error

3. Update electron-builder.config.cjs

To ensure electron-builder packages cleanly without certificate signing errors, update the win block in electron-builder.config.cjs:

    win: {
        target: ["nsis", "msi", "zip"],
        signtoolOptions: windowsShouldSign
            ? {
                  signingHashAlgorithms: ["sha256"],
                  publisherName: "Command Line Inc",
                  certificateSubjectName: "Command Line Inc",
                  certificateSha1: process.env.SM_CODE_SIGNING_CERT_SHA1_HASH,
              }
            : undefined,
    },

4. Trigger the Build

1. Commit and push these changes to your fork.
2. In your fork on GitHub, go to Actions > Build Helper.
3. Click Run workflow (select main branch).
4. The workflow will run on GitHub-hosted windows-latest and will:
   • Build wavesrv.x64.exe using Go + Zig CGO cross-compilation.
   • Build wsh binaries.
   • Bundle the frontend via Vite.
   • Package the app with electron-builder.

5. Download the Installer

Once the run finishes (~18 minutes):

1. Navigate to the completed run page under the Actions tab.
2. Under Artifacts, download wave-windows-x64-installer.
3. Unzip the artifact to find:
   • Wave-win32-x64-<version>.exe (NSIS installer)
   • Wave-win32-x64-<version>.msi (MSI installer)
   • Wave-win32-x64-<version>.zip (Portable build)

---

Verified on latest main commit 9f1c967.