hex/docs/test-builds.md
Dax 538d16f668
windows: sign the setup engine so smart app control can run setup (#1987)
* windows: sign the setup engine so smart app control can run setup

Setup extracts a copy of its engine to %TEMP% at launch and writes the
installed uninstaller from the same bytes. Signing only the outer
hex-setup-*.exe left both unsigned, and Windows 11 Smart App Control
blocked the extracted copy ("Unable to execute file in the temporary
directory", error 4551).

SignedUninstaller embeds the engine's signature, but the signature has to
exist before the compile that uses it, and the compile job holds no
credentials. So the release signs it in two passes: the new
windows-setup-engine.yml compiles once with SignedUninstaller=yes and keeps
the unsigned uninst-*.e32 ISCC asks to be signed (ISCC leaves it and aborts
as a compile failure, exit 2); sign-windows-engine signs and verifies it in
the release environment; windows-installers.yml then compiles with the
signed engine and asserts the installed uninstaller's signature.

Test builds and runs without the Azure values keep the unsigned single
compile. Inno Setup is pinned to 6.7.1, read from the compiler's own banner
(ISCC.exe's version resource is 0.0.0), so both passes use one compiler.

* windows: harden the setup engine passes

Review fixes for the signed setup engine:

- sign-windows-engine requires sign-windows to have succeeded, and its
  steps are unguarded like sign-windows-installers, so it can never upload
  an empty digest.
- setup-engine runs only when Windows is signed (it waits for
  sign-windows), so unsigned runs really do a single compile with no
  engine pass at all.
- the Inno re-pin uses choco upgrade --allow-downgrade, because choco
  install --version treats a preinstalled package as already installed.
- Invoke-Iscc collects native stderr safely under Windows PowerShell 5.1
  and pwsh with $PSNativeCommandUseErrorActionPreference on, and echoes
  the compiler's lines so build logs stay readable.
- the version probe compiles a minimal script from standard input into a
  throwaway OutputDir, so it never touches the caller's -OutDir.
- only .e32 exists for the engine; drop the unused .e64 handling.
- the uninstaller signature test also checks the release publisher, and
  the test-builds doc warns that Smart App Control cannot be turned back
  on without resetting Windows.

* windows: correct the setup engine comments
2026-11-19 02:38:03 -05:00

3.8 KiB

Test Builds

Every push to dev runs the Test builds workflow (.github/workflows/test-builds.yml; run it by hand with Run workflow). Open the latest green run: its summary links each download. Artifacts are kept 14 days, and downloading one requires a GitHub login with access to the repository.

hex-test-<commit>-macos-arm64       // hex-test-<commit>-arm64.dmg
hex-test-<commit>-windows-x86_64    // hex-setup-<version>-windows-x64.exe + bare hex-<version>-windows-x64.exe
hex-test-<commit>-windows-aarch64   // hex-setup-<version>-windows-arm64.exe + bare hex-<version>-windows-arm64.exe
hex-test-<commit>-linux-x86_64      // hex-<version>-linux-x64

None of these are code-signed, notarized, or published. They never update themselves, so the signed release cannot replace the build you are testing. GitHub wraps each artifact in a zip; unzip it first.

macOS (Apple silicon, macOS 15 or later)

The test app is Hex Test.app (bundle ID anomaly.hex.test), ad-hoc signed and never checks for updates. Its own name and bundle ID let it sit beside a released Hex.app without touching that app's permissions, login item, or updates. It also keeps its own data: settings, models, History, and meetings live in ~/Library/Application Support/hex-test, personal commands in ~/.config/hex-test, and meeting Markdown in ~/Documents/Hex Test Meetings, so it starts with onboarding and never reads or changes the installed Hex's data. Both apps listen to the same shortcut and microphone, so run one at a time.

  1. Quit Hex from its menu-bar icon.

  2. Open the DMG and drag Hex Test to Applications.

  3. Clear the download quarantine, which macOS otherwise reports as an app that cannot be opened or is damaged:

    xattr -dr com.apple.quarantine "/Applications/Hex Test.app"
    

    Alternatively, open it once, then choose Open Anyway in System Settings → Privacy & Security.

  4. Open Hex Test and grant Microphone and Accessibility again. Ad-hoc signatures change with every build, so each new test build needs these grants again: remove the old Hex Test entries in System Settings and add the new app.

To go back, quit Hex Test, delete it, and open Hex.

Windows (10 or 11, x64 or ARM64)

The installer and executable are unsigned, so SmartScreen warns: choose More info, then Run anyway. Smart App Control is stricter: it blocks an unsigned setup engine, and turning it off cannot be fully undone without resetting Windows. Use a VM, or a machine where it is already off; release installers carry the signed engine and work with it on.

  1. Quit Hex from its tray icon.
  2. Run hex-setup-<version>-windows-<x64|arm64>.exe. It replaces an installed Hex of the same or an older version in the usual per-user layout, and refuses to replace a newer one: uninstall that first from Apps & Features (settings are kept). Or skip the installer and run the bare hex-<version>-windows-<arch>.exe from any folder.
  3. The test build never self-updates. To return to the release, run the release installer from https://anoma.ly/hex.

Linux (x86_64)

An installed Hex starts through its systemd user unit, so launching the test binary normally would just start the installed one. Run the test binary as the instance directly instead:

hex quit
chmod +x hex-*-linux-x64
./hex-*-linux-x64 service     # runs Hex in the foreground; Ctrl-C quits
./hex-*-linux-x64             # in another terminal: opens the window

After Ctrl-C, hex starts the installed Hex again.

Reporting

Include the commit from the artifact name, the OS and architecture, and the logs: ~/Library/Application Support/hex/logs/ on macOS, %LOCALAPPDATA%\hex\logs\ on Windows, and ~/.local/share/hex/logs/ on Linux.