Every macOS app that isn't distributed through the Mac App Store has to earn Gatekeeper's trust the hard way — through a chain of cryptographic signatures and an online check-in with Apple before the OS will let a user double-click it. Influxx made that chain narrower than most: Apple Silicon only, no Intel build, no App Store listing at all. That narrowness didn't make the notarization problem easier. It just meant there was exactly one pipeline to get right, and no fallback build to hide behind if it broke.
Why Influxx Skipped Intel and the App Store Entirely
Building a universal binary — one that runs natively on both Apple Silicon and Intel Macs — roughly doubles the signing and notarization surface for a desktop app of any complexity. Every nested helper binary has to be built, signed, and verified twice, once per architecture, and every regression has to be checked against both. For a developer-tooling app like Influxx, whose target audience runs coding agents locally and is disproportionately likely to already be on Apple Silicon hardware, that cost didn't buy much. The decision was to ship arm64 only.
The Mac App Store was ruled out for a related but distinct reason: App Store distribution comes with its own sandboxing constraints, review process, and entitlement restrictions that don't mesh cleanly with what Influxx actually does — spawning real PTYs, running a background daemon that survives app restarts, and shelling out to dozens of third-party coding-agent CLIs. Independent distribution, outside the App Store, was the only path that let the app behave like the terminal-and-git tool it actually is. But independent distribution means Gatekeeper has nothing to go on except what the release pipeline proves to Apple at build time.
The Four Things Gatekeeper Actually Requires
Gatekeeper's check on first launch isn't a single pass/fail gate — it's a chain of four separate requirements, and skipping any one of them produces a different failure mode for the user (a straight "can't be opened" dialog, a "damaged" warning, or a silent bounce in Finder). For independent, non-App-Store distribution on macOS, all four have to be present:
- Developer ID Application code signature: the app binary and every nested executable inside it must be signed with an Apple-issued Developer ID certificate, proving the binary traces back to a real, registered developer account.
- Hardened Runtime: a runtime capability enabled at signing time that restricts what the process can do — code injection, dyld environment variable abuse, unsigned memory execution — closing off exactly the kind of tampering vectors Gatekeeper is designed to catch.
- Notarization by Apple's notary service: the signed, hardened build is uploaded to Apple, which scans it and returns a ticket confirming it found nothing malicious.
- Stapling: the notarization ticket gets physically attached to the shipped artifact, so Gatekeeper can verify it offline without a network round-trip to Apple every time.
Miss the Hardened Runtime flag and notarization itself will be rejected outright — Apple's notary service won't issue a ticket for a binary that doesn't have it enabled. Sign but skip notarization and the app opens with an ominous unidentified-developer warning that most users won't click through. Notarize but skip stapling and the app still works, but only because Gatekeeper falls back to an online check against Apple's servers the first time it's opened — which is exactly the subtlety that caused a real problem during a recent release.
"People think of notarization as one step, but it's really four separate proofs and Gatekeeper checks all of them independently. If you get the hardened runtime entitlements wrong, Apple's notary service won't even accept the upload — you find out in minutes, not after a user reports the app won't open."
— Priya Nandan, Release Engineering Lead at ETAPX
Signing Order Matters More Than It Looks Like It Should
Influxx isn't a single executable — it's an outer application bundle with several nested native helper apps sealed inside it: a Computer Use helper that handles OS-level automation, a notification-status helper, and a menu-bar notch host helper that manages the app's system-tray presence. Each of these is its own signed Mach-O binary with its own bundle identifier, and each one has to be individually signed with the Developer ID Application certificate and Hardened Runtime enabled before the outer application gets its own signature applied.
The reason is structural, not stylistic. Code signing on macOS works by sealing a cryptographic hash of everything inside the bundle at the moment of signing. If you sign the outer app first and then modify or sign anything nested inside it afterward, you've changed the contents the outer signature already vouched for — and that invalidates the outer signature even though nothing malicious happened. The fix is strict ordering: helpers first, container last, every time, with no manual shortcuts that touch the bundle after the outer seal is applied.
A Credential Preflight That Runs Before Packaging Even Starts
Signing failures are the kind of thing you want to catch in seconds, not after a twenty-minute build finishes. Influxx's release pipeline runs a dedicated credential-preflight script automatically before packaging begins, specifically to check that every signing environment variable and credential the build will need — the Developer ID certificate, notarization API credentials, and related secrets — is actually present and valid. If something is missing, the script fails loudly before a single binary gets compiled, instead of letting a broken release quietly assemble itself and fail (or worse, half-succeed) an hour later.
"We added the preflight after watching a build eat twenty minutes of compile and packaging time only to fail on a missing notarization credential at the very last step. Now that same failure happens in under a second, before anything expensive even starts."
— Marcus Deveraux, Senior Platform Engineer at ETAPX
The Disk-Image Stapling Gotcha
Here's the detail that catches even experienced macOS release engineers off guard, and that Influxx's team hit directly while shipping a release candidate: stapling the notarization ticket to the disk-image installer — the .dmg users actually download — often fails outright with a "record not found" error.
The reason is that Apple's notary service, and the packaging tooling that talks to it, notarizes the application bundle itself, not the disk-image container wrapped around it. The .dmg is just a delivery mechanism; the thing Apple's scanners actually inspected and issued a ticket for is the .app bundle sitting inside it. Asking the stapler to attach that ticket to the outer disk image is asking it to staple something to a container that was never the subject of the notarization request in the first place — hence the failure.
The practical consequence is less alarming than the error message suggests. Users who download the disk image and open the app for the first time still get a fully notarized experience — Gatekeeper simply checks the ticket online against Apple's servers at that first launch, since the ticket lives with the app bundle rather than being physically stapled to the disk image container. The staple-to-app approach still delivers everything Gatekeeper needs; it just delivers it as an online check on first run for the .dmg path rather than a fully offline one for the container itself. Knowing this in advance — instead of treating the "record not found" error as a build failure — is the difference between a five-minute non-issue and a stalled release.
"I'd never thought about the difference between notarizing an app and notarizing the disk image it ships in until I read through Influxx's release notes for one of their release candidates. It explained a 'record not found' error I'd hit on my own tooling for a side project and couldn't figure out for a week."
— Sofia Reyes, infrastructure engineer at a data-platform startup, Influxx user
What a Verified Local Release Build Actually Produces
A successful local release run against the real signing credentials produces three artifacts together, matching what the pipeline is designed to ship:
- A signed installer disk image — the .dmg users download and drag into Applications.
- A zipped app bundle — the .app packaged as a .zip, used for update distribution and as an alternate artifact for automated checks.
- An update-feed manifest file — the metadata file the app's auto-updater reads to know a new version exists and where to fetch it.
All three coming out of one build run is the signal that the pipeline did its job end to end — signing, hardened runtime, notarization submission, and stapling all completed without an engineer needing to intervene mid-build.
Three Commands, Run Every Time Before Anything Ships
Producing the artifacts isn't the same as proving they're correctly signed and notarized. Influxx's release process runs post-build verification using three well-known macOS command-line tools before any artifact is allowed to ship: `codesign` to verify the code signature and hardened runtime flags are actually present and valid on the binary, `spctl` to run the same assessment Gatekeeper itself performs when a user opens the app, and `stapler` to confirm the notarization ticket is correctly attached and validates. Running all three isn't redundant — each one checks a different layer of the same four-part chain, and each has independently caught problems the others missed during earlier releases.
Locking the Release Pipeline to the Real Repository
Signing credentials being present is necessary but not sufficient — they also need to be unreachable from anywhere except the actual release process. Influxx's release build is gated in CI to only run from the project's official repository, and only when dispatched from a release-cut job targeting a draft version tag. A fork, a pull request from an untrusted branch, or a manually triggered workflow run outside that specific path simply cannot reach the signing credentials or trigger a notarization submission, regardless of what CI configuration it contains.
This matters more for a Developer ID pipeline than it might for other kinds of CI secrets. A leaked or misused notarization credential doesn't just expose a service — it can be used to get a signed, notarized, Gatekeeper-trusted binary in front of real users. Restricting the release path to the official repository and a specific, human-initiated dispatch step is the control that keeps that risk bounded.
"The whole point of Gatekeeper is that Apple is vouching for a chain of trust that starts with us. If our release pipeline could be triggered from a random fork or a stray branch, we'd be asking Apple's notary service to vouch for something we didn't actually control. Locking the release job to the real repository and a real release-cut dispatch is table stakes for being allowed to keep using that trust at all."
— Renata Оsei, VP of Engineering at ETAPX
Why This Level of Rigor Is the Actual Payoff
None of this is visible to a developer who downloads Influxx, opens the .dmg, and drags the app to their Applications folder. That's the point. A correctly notarized, correctly stapled, correctly signed release is invisible — it just opens. Every piece of the pipeline described here exists to prevent the alternative: a Gatekeeper warning dialog, a "damaged and can't be opened" message, or an app that technically works but makes a security-conscious developer immediately distrust the tool asking to spawn terminals and touch their git worktrees. For a desktop app whose entire value proposition rests on being trusted with real shell access and real repositories, that first-run experience is not a cosmetic detail.
Frequently Asked Questions
Why doesn't Influxx ship an Intel (x64) build for macOS?
Influxx ships Apple Silicon (arm64) only, with no Intel build. Building and maintaining a universal binary would double the signing, notarization, and testing surface for every release, for an architecture increasingly uncommon among the app's target developer audience.
Is Influxx available on the Mac App Store?
No. Influxx uses independent, non-App-Store distribution exclusively, signed with a Developer ID Application certificate and notarized directly through Apple's notary service rather than through App Store review.
What happens if a nested helper app is signed after the outer app bundle?
Signing the outer app bundle seals a cryptographic hash of everything inside it. Signing or modifying a nested helper — such as the Computer Use helper or the notch host helper — after that point invalidates the outer signature, which is why all nested helpers must be signed first.
Why did stapling the notarization ticket to the .dmg fail with "record not found"?
Apple's notary service and packaging tooling notarize the application bundle itself, not the disk image wrapping it, so attempting to staple the ticket directly to the .dmg container fails. The app inside is still fully notarized, and Gatekeeper validates it via an online check against Apple's servers the first time a user opens it from the disk image.
Does skipping the disk-image staple mean users get a less secure experience?
No. The app bundle itself carries full notarization; the only difference is that Gatekeeper's first check happens online against Apple's servers rather than fully offline against a locally stapled ticket, which only affects the very first launch.
How does the pipeline prevent a broken release from shipping silently?
A credential-preflight script runs automatically before packaging starts to confirm all required signing environment variables and credentials are present, and post-build verification runs `codesign`, `spctl`, and `stapler` to confirm the resulting artifacts are actually correctly signed and notarized before anything ships.
Can a fork or an untrusted branch trigger a real signed release build?
No. The release build is gated in CI to run only from the project's official repository, and only when dispatched from a release-cut job against a draft version tag, so signing credentials and notarization submission are unreachable from forks or arbitrary branches.
Notarization isn't a certificate you obtain once — it's a chain of four independently-checked proofs that has to be rebuilt correctly on every single release, in the right order, with the right credentials verified before the build even starts. Betting narrow on Apple Silicon only didn't remove that complexity; it just meant Influxx's team had exactly one pipeline to get exactly right.
