macOS releases are signed with a stable self-signed certificate (CN OhMyHF-Release) so
Squirrel.Mac accepts auto-updates; local macOS builds stay ad-hoc (identity: '-').
Windows and Linux remain unsigned. This document explains the current scheme and tracks what
is needed for real Developer ID signing + notarization.
Until Developer ID signing is configured, in-app installation trusts the GitHub repository and
release credentials as the update root: the downloaded artifact must match the SHA-512 value in
the release manifest, but that manifest is not an independent publisher signature. On macOS,
Squirrel.Mac additionally requires updates to embed the same OhMyHF-Release certificate as the
installed app, which pins updates to holders of the CI signing secrets. Installation still
requires both the renderer action and a native main-process confirmation.
Squirrel.Mac does not literally require Developer ID: before installing an update it checks that the downloaded app satisfies the designated requirement (DR) of the running app. What kind of DR you get depends on the signature:
- ad-hoc (
identity: '-') → DR iscdhash H"…", unique per build → validation can never pass, so ad-hoc apps cannot auto-update. - any real certificate → DR is
identifier "dev.oh-my-huggingface.desktop" and certificate root = H"<hash of the certificate>"→ stable across versions as long as every release is signed with the same certificate. Evaluating this DR on the user's machine hashes the embedded certificate; it does not require the certificate to be trusted there.
So releases are signed with a self-signed code-signing certificate (CN OhMyHF-Release,
generated once, valid until 2036). Release N validates release N+1 because both embed the same
certificate. The private key lives in ~/.ohmyhf-signing/ on the maintainer machine (keep a
backup — losing it means one manual-update transition for every user) and as the repo secrets
MAC_CSC_LINK (base64 .p12) / MAC_CSC_KEY_PASSWORD.
How the pieces fit:
apps/desktop/package.json→build:mac:releaseoverrides the identity with-c.mac.identity=OhMyHF-Release; plainbuild:mackeeps ad-hoc for local builds..github/workflows/release.ymlimports the.p12into a throwaway keychain and runssudo security add-trusted-cert -d— electron-builder only accepts identities thatsecurity find-identity -v -p codesigninglists as valid, which requires trust on the build machine (runners have passwordless sudo). End users never need this.mac.forceCodeSigning: trueinelectron-builder.ymlfails the release build instead of silently shipping an unsigned (broken-seal) app if the secrets are missing.macAutoInstallEnabledinapps/desktop/src/main/index.tsistrue: macOS downloads and installs updates in-app like the other platforms.
Constraints of this scheme:
-
Certificate rotation is a breaking change. A new certificate has a new hash, so the DR of installed apps no longer matches — every user must install the next release manually once. The same applies to the upgrade to Developer ID later, and to users on releases from before the first self-signed build (they see the manual-install fallback for one version).
-
The self-signed certificate is not notarized and not trusted by Gatekeeper. First launch after a browser download may still need:
xattr -dr com.apple.quarantine "/Applications/Oh My HuggingFace.app"or right-click the app → Open → Open. Auto-updates are unaffected: Squirrel.Mac installs without re-triggering quarantine.
- Join the Apple Developer Program and create a Developer ID Application certificate.
- Export the certificate as
.p12and add repository secretsCSC_LINK(base64) andCSC_KEY_PASSWORD. - Create an App Store Connect API key for notarization; add
APPLE_API_KEY,APPLE_API_KEY_ID,APPLE_API_ISSUERsecrets. - In
apps/desktop/package.jsonreplace thebuild:mac:releaseidentity override with the Developer ID name (or rely onCSC_LINK), keephardenedRuntime/ entitlements, and addnotarize: true. - Replace the "Import macOS signing certificate" step in
.github/workflows/release.ymlwith the standardCSC_LINK/CSC_KEY_PASSWORDflow (Developer ID certificates are Apple-trusted, so the manual keychain +add-trusted-certdance is unnecessary). - Ship one transition release: apps signed with the self-signed certificate cannot validate a Developer ID–signed update, so that hop is a one-time manual install for existing users.
Unsigned installers show a SmartScreen warning. Options: an OV/EV code-signing certificate
(set CSC_LINK/CSC_KEY_PASSWORD for the Windows job) or Azure Trusted Signing
(azureSignOptions in electron-builder).
AppImage/deb do not require signatures. Optionally publish a GPG-signed checksum file alongside releases.