Signing everything: Apple notarization, Azure Artifact Signing and GPG in one CI pipeline

How OpenVireo signs every desktop build, CLI binary and server release in GitHub Actions, ships Ed25519-signed auto-updates, and the gotchas that cost the most time.

By 7 min read

A password manager asks people to trust it with everything. The least it can do is prove that the file they downloaded is the one I built. For OpenVireo, that means every release, and every nightly, is signed on every platform:

WhatmacOSWindowsLinux
Code signingDeveloper ID + notarizationAzure Artifact SigningGPG signature embedded in the AppImage
Auto-updateSparkle 2WinSparkleAppImageUpdate (zsync)
Update signatureEd25519Ed25519GPG
ChecksumsSHA256SUMS.txt + GPG signature, everywhere

The same setup signs the ov CLI binaries and the self-hosted sync server. All of it runs in GitHub Actions, with no signing key on my laptop. This post walks through the pieces and the problems that took the longest to solve.

Principles

  • Each part turns on by itself. Every signing step checks for its secrets. Without them, the workflow builds unsigned packages and prints a warning saying what it skipped. Forks and pull requests still build, and nothing fails because someone hasn’t set up an Apple account.
  • Signing only runs where it should. The secrets live in a GitHub environment called signing, restricted to the develop branch and version tags. A pull request from a fork can’t reach them.
  • Downloads are pinned. Sparkle, WinSparkle and the Azure signing client are downloaded by version and SHA-256. Updating one means updating both.

macOS: Developer ID and notarization

The most familiar of the three. The workflow imports a Developer ID Application certificate from a base64 secret into a temporary keychain, signs the app bundle (and its AutoFill extension, with its own provisioning profile), and submits it to Apple’s notary service with an app-specific password.

Two things worth knowing:

  • A bare executable can’t carry a notarization ticket. An .app or .dmg can have the ticket stapled to it, so Gatekeeper can check it offline. A single binary like the ov CLI can’t, so the first run checks it with Apple online. It still works when downloaded with a browser; it just needs a network connection the first time.
  • Entitlements depend on the runtime. The C++ sync server needs none. The CLI is built with Bun’s --compile, which embeds a JIT, and under the hardened runtime it needs exactly one entitlement: com.apple.security.cs.allow-jit. Without it, the signed binary dies at launch.

Windows: Azure Artifact Signing over OIDC

Windows code signing used to mean buying a certificate and keeping a hardware token somewhere. Azure Artifact Signing replaces that: Microsoft holds the key, verifies your identity once, and signs on request. SignTool calls it through a “dlib” plugin, so the build signs .exe, .dll and .msi files as usual.

Authentication uses OIDC federation, so there’s no client secret anywhere. GitHub issues a short-lived token for the job, and Azure trusts it because of a federated credential that names the repository and environment. Two problems came up here.

Problem 1: the subject didn’t match

The federated credential has to match the token’s sub claim exactly. The docs show subjects like repo:OpenVireo/openvireo:environment:signing. My repository sends immutable subjects, which include the numeric owner and repository IDs, so the real subject was:

repo:OpenVireo@347287727/openvireo@1432261311:environment:signing

The error message just says the assertion didn’t match. The quickest way to see what your repository actually sends:

Terminal window
gh api repos/OWNER/REPO/actions/oidc/customization/sub

Problem 2: the token expired mid-build

The first signed build failed with AADSTS700024, a client assertion outside its valid time range. azure/login signs in with GitHub’s OIDC token, which is only valid for a few minutes, and the Azure CLI can’t renew a federated login on its own. A desktop build takes much longer than a few minutes, so by the time SignTool ran, the login had expired.

The fix is a small script that runs in the background for the whole build. Every four minutes it fetches a fresh OIDC token from GitHub, logs in again, and gets a code-signing token ahead of SignTool:

Terminal window
while true; do
token=$(curl -fsS -H "Authorization: Bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN" \
"$ACTIONS_ID_TOKEN_REQUEST_URL&audience=api://AzureADTokenExchange" \
| python -c 'import json, sys; print(json.load(sys.stdin)["value"])')
if [ -n "$token" ] \
&& az login --service-principal --username "$AZURE_CLIENT_ID" \
--tenant "$AZURE_TENANT_ID" --federated-token "$token" \
--allow-no-subscriptions --output none \
&& az account get-access-token --resource https://codesigning.azure.net --output none; then
echo "Azure login refreshed for Artifact Signing"
else
echo "::warning::Could not refresh the Azure login for Artifact Signing"
fi
sleep 240
done

It needs id-token: write on the job. Inelegant, but it has worked on every build since.

Linux and checksums: GPG

GPG signs the AppImages and the SHA256SUMS.txt file attached to every release. The key setup follows the usual advice:

  • The primary key is certification-only, kept offline, and its public half is published on the website and keys.openpgp.org.
  • CI gets a signing subkey, exported without a passphrase (--export-secret-subkeys <fingerprint>!, the ! meaning “only this subkey”), removed from a temporary GNUPGHOME copy only. If it leaks, I revoke the subkey and issue a new one; the primary key and everyone’s trust in it stay.

I learned why that split matters the hard way: I lost the passphrase of my first release key. Because CI only ever had a subkey, replacing it meant creating a new key, publishing it, revoking the old one on keys.openpgp.org, and updating one secret in three repositories. No build had my primary key in it.

Release tags are signed too, by me, locally, because the primary key needs its passphrase. The tag starts the release workflow.

Auto-updates: Ed25519 appcasts

Signing the installer protects the first download. Auto-update needs its own chain of trust, or anyone who can change the update feed can push a binary to every user.

Sparkle (macOS) and WinSparkle (Windows) both verify an Ed25519 signature of each update against a public key compiled into the app. The key is made once, offline, with plain OpenSSL:

Terminal window
openssl genpkey -algorithm ed25519 -out update-key.pem
openssl pkey -in update-key.pem -pubout -outform DER | tail -c 32 | base64

The private key is a secret, the public key a variable. The publishing job refuses to write a feed if the two don’t match, which catches the classic mistake of rotating one and not the other. Losing the private key means existing installs can never update again, so there’s an offline backup.

The feeds themselves are appcast files attached to GitHub releases, one per platform and architecture:

stable: /releases/latest/download/appcast-<os>-<arch>.xml
nightly: /releases/download/nightly/appcast-<os>-<arch>.xml

That gives two channels for free:

  • releases/latest skips drafts and pre-releases, so a release’s feed only goes live when I publish its draft. A release workflow can build and sign everything, I check the draft, and users only see it after that.
  • Nightlies append the UTC date and hour as a fourth version component (1.0.0.26112103), so a nightly sorts above the release it was built from and below the next one. Users can switch channel in the settings.

This is also why releases before 1.0 were full releases titled “beta” rather than GitHub pre-releases: a pre-release never appears at releases/latest, so the stable feed would never have offered it.

Smoke-testing signed binaries

A signature that verifies doesn’t mean the binary runs. The CLI and server releases run a smoke test of the signed artifact on native runners for each OS (including an Intel Mac). It turned up a few surprises:

  • Git Bash on Windows drops .exe. It finds foo.exe when you ask for foo, which is helpful until your script compares file names.
  • MSYS2_ARG_CONV_EXCL='*' breaks native OpenSSL paths. Turning off MSYS path conversion for everything also turns it off for the arguments that needed it.
  • A timeout isn’t a pass. One test checks that the server refuses an untrusted certificate. A fetch that timed out was being counted as “refused”. It now has to fail for the right reason.
  • System OpenSSL configs differ. The fully static Linux server crashed on Fedora with “Failed to create SSL context”, because it picked up Fedora’s openssl.cnf, which references modules a static build doesn’t have. Portable builds now skip the system config (an explicit OPENSSL_CONF still overrides it).

How users check it

All of this only helps if people can verify it. The website has a verifying signatures page with the key fingerprint and the commands:

Terminal window
curl -sSL https://openvireo.com/openvireo-release.asc | gpg --import
gpg --verify SHA256SUMS.txt.asc SHA256SUMS.txt
sha256sum --ignore-missing -c SHA256SUMS.txt

On macOS, spctl --assess -vv should say source=Notarized Developer ID. On Windows, Get-AuthenticodeSignature should say Valid.

What I’d tell someone starting out

  • Put signing secrets in a protected environment limited to your release branches and tags, not in plain repository secrets.
  • Use OIDC wherever the provider supports it, and check the real sub claim before writing the trust policy.
  • Give CI a subkey, never the primary key.
  • Sign updates separately from installers, and make the publish step check the key pair.
  • Smoke-test the signed artifact on each OS. Signing changes the binary, and the binary is what users run.

The workflows are public in the openvireo, openvireo-sdk and openvireo-sync-server repositories.