Release Shark Explorer separately from LeakCanary

[pyricau]

Shark Explorer is a desktop app, not a library, so it ships as a signed macOS DMG on a GitHub release rather than to Maven Central. This adds the machinery for that: its own version line, its own tags, its own release workflow, and an in-app check that tells you when a newer release exists.

Nothing here changes anything about how LeakCanary itself is released.

The version can't say "alpha", and that isn't a preference

Every installer format validates the version, and I measured what they leave between them by building each one:

Version	Result
3.0-alpha-10	Illegal version for 'Dmg', and for Msi. No qualifiers, in any format.
0.1.0	createDistributable fails: The first number in an app-version cannot be zero or negative
2026.8.0, 256.0.0	Illegal version for 'Msi', whose fields cap at 255.255.65535
1.0.0, 255.255.65535	Build fine

So the intersection is MAJOR.MINOR.PATCH with a major from 1 to 255. There is no number that means "before 1.0" — not 0.x, not a calendar version, no qualifier. The alpha is said by the release instead: release-shark-explorer.yml marks every release as a prerelease and titles it Shark Explorer <version> (alpha).

Splitting it across macOS.packageVersion and macOS.packageBuildVersion doesn't help either. The user-visible field is CFBundleShortVersionString, which is also what Munki compares for Managed Software Center updates, so pinning it would freeze updates for anyone who installed from there.

Signing

Through block/apple-codesign-action, which signs and notarizes with Block's Developer ID through an internal service the workflow reaches over OIDC. No certificate or Apple credential lives in this repository — that's what makes signing a public repo's artifacts safe, and it's how block/qrgo and block/buzz are signed.

It needs two repository secrets, OSX_CODESIGN_ROLE and CODESIGN_S3_BUCKET, provisioned by #mdx-ios. Until those exist the macos jobs will fail, so the first release can't be cut yet. Everything else in here works today.

entitlements.plist isn't optional: every key in it is something the JVM does that the hardened runtime forbids, so a notarized build without them launches and immediately dies.

The service signs the .app and rebuilds the DMG around it, so the DMG container itself stays unsigned. The workflow runs codesign --verify, stapler validate and spctl --assess on the app inside the DMG and prints what they say, rather than assuming.

The update check reports and nothing else

A bar naming the new version, a link, and a way to dismiss it. No self-update: replacing a running signed bundle needs a native helper, and that's a much bigger thing to get right than a link.

Two decisions worth calling out:

• It doesn't use releases/latest. GitHub has one "latest" pointer per repository, and this repo publishes LeakCanary on v* tags, so that endpoint answers with the wrong release — it currently returns v3.0-alpha-9. The unauthenticated API is also 60 requests an hour per IP, which a shared corporate egress can exhaust. The app reads one small manifest off the release download CDN, which is unmetered.
• Only promote-shark-explorer.yml writes that manifest. So publishing a release and offering it to everyone are two separate acts, and a release that turns out to be broken is one nobody was told about rather than one that has to be withdrawn.

Its own change log

Two release schedules means two change logs, so docs/shark-explorer-changelog.md is new and a Shark Explorer change never goes in the LeakCanary one — it would otherwise show up under a LeakCanary release it has nothing to do with. Same markers, minus 🐤, which is a library thing. It starts at ## Unreleased with * ✨ Initial release.

A change log nobody is told to update ships empty, so the release process now says so: cutting a version includes renaming the Unreleased heading, and there's a step to deploy the site, since the release notes link to the page.

Verified, not assumed

• ./gradlew build green; :shark:shark-explorer:shark-explorer-app:check green with 22 new tests.

• packageDmg builds a 69 MB DMG whose Info.plist carries com.squareup.leakcanary.shark-explorer and version 1.0.0, with the generated version resource inside the packaged jar.

• The app launched and the live check ran against the real URL: latest.properties answered 404, logged, no bar, on a worker thread. That's the expected answer until the first promotion.

• Both workflows parse, and the tag/version check and manifest-writing shell were run locally. UpdateCheckTest pins the manifest format from the app's side, since the workflow writes it in bash and nothing else keeps the two agreeing.

• mkdocs build renders both new pages with no broken links; the only warnings are the pre-existing ones for docs/api, which siteDokka generates and isn't committed.

Known gap

There's no user-facing Shark Explorer docs page yet, so the release notes describe the app rather than linking to one. Worth writing before the first release goes out, since discoverability is the point — it's being written separately and will land in the same Shark Explorer nav section as the change log.

🤖 Generated with Claude Code