Skip to content

Commit 54e364a

Browse files
ndemiancclaude
andcommitted
feat(release): emit a signed .app.zip update asset (auto-update S1)
The built-in Squirrel updater installs from a .zip of a Developer-ID-signed app, never a .dmg — so the update feed has had no valid asset to point at, and the server deliberately served 204 to it. make-dmg.sh now also emits LevelCode-<arch>.app.zip (+ .sha256) from the app it has ALREADY signed, notarized and stapled, on the Developer-ID path only: an ad-hoc build must never be served as an update. `ditto` (not `zip`) preserves the stapled ticket so the updated app validates offline, and puts LevelCode.app at the zip root as Squirrel requires. Inert on its own — nothing changes until the feed serves the asset (S2). The .dmg remains the fresh-install path. - docs/AUTO-UPDATE.md: scope, slices, risks (signing-identity continuity, sequencing, no staged rollout) and the exit test - docs/RELEASING.md: upload both assets; §5 rewritten — the stale tools/update-server reference is gone (the feed is GitHub Releases via thin.ly) - release.yml: draft-release instructions updated to match Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
1 parent 3943d66 commit 54e364a

4 files changed

Lines changed: 143 additions & 10 deletions

File tree

‎.github/workflows/release.yml‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -106,8 +106,9 @@ jobs:
106106
1. `gh release download ${{ github.ref_name }} --pattern 'UNSIGNED-*.app.zip'`
107107
2. For each arch — unzip into `VSCode-darwin-<arch>/`, then
108108
`CODESIGN_IDENTITY="Developer ID Application: …" NOTARY_PROFILE=levelcode-notary ./scripts/make-dmg.sh <arch>`
109-
(signs → dmg → notarizes → staples → `LevelCode-<arch>.dmg`).
110-
3. `gh release upload ${{ github.ref_name }} LevelCode-arm64.dmg LevelCode-x64.dmg`
109+
(signs → notarizes → staples → `LevelCode-<arch>.dmg` **and** `LevelCode-<arch>.app.zip`).
110+
3. `gh release upload ${{ github.ref_name }} LevelCode-arm64.dmg LevelCode-x64.dmg LevelCode-arm64.app.zip LevelCode-x64.app.zip`
111+
— the `.dmg`s are for humans, the `.app.zip`s are the auto-update feed assets (`docs/AUTO-UPDATE.md`).
111112
4. **Delete the `UNSIGNED-*.app.zip` assets**, add real notes, and publish.
112113
113114
Full runbook: `docs/RELEASING.md`.

‎docs/AUTO-UPDATE.md‎

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
# LevelCode — Signed auto-update (Squirrel `.zip`) — scope
2+
3+
**Goal:** make the editor's built-in **Check for Updates…** actually install a new build, instead of
4+
always reporting "There are currently no updates available."
5+
6+
**Today:** that dialog is *correct behaviour*, not a bug. `Api::UpdatesController` (thin.ly) serves
7+
**204** to every client except the notify-only extension — a deliberate **unsigned-build guard**,
8+
because the built-in Squirrel updater *auto-downloads and installs* whatever `url` a 200 returns, and
9+
today that `url` is a GitHub **release page**, not a signed `.zip`. Squirrel would download it and fail.
10+
11+
Verified against production while scoping:
12+
13+
| Client | Request | Response |
14+
|---|---|---|
15+
| Built-in Squirrel updater | `GET /api/update/darwin-arm64/stable/<commit>` | **204** (guard) |
16+
| Notify-only extension (`User-Agent: LevelCode Updater`) | same | **200** `productVersion: 0.7.2` |
17+
18+
## What already exists (most of the hard part)
19+
20+
- **`scripts/notarize.sh sign`** — Developer ID signing with **hardened runtime** + `levelcode.entitlements`.
21+
- **`scripts/notarize.sh notarize-app`** — notarizes **and staples the `.app` itself**, precisely so a
22+
copied-out app validates offline. **This is exactly the artifact Squirrel needs.**
23+
- **CI already zips an app** with `ditto -c -k --sequesterRsrc --keepParent` (for the UNSIGNED artifact) —
24+
the same command, applied to the *signed* app, produces the feed asset.
25+
- **`Api::UpdatesController`** already implements the full Code-OSS feed contract, the guard, and
26+
`LEVELCODE_UPDATE_FEED` (a JSON env override) — which doubles as the **rollback/pin lever**.
27+
- **`Levelcode::EditorReleaseFeed`** already resolves tag → commit, `product_version`, and timestamp.
28+
29+
So this is **not** a new signing pipeline. It is: publish one more asset, teach the feed to point at it,
30+
then lift the guard.
31+
32+
## The gap
33+
34+
1. **Release artifact.** Produce `LevelCode-<arch>.app.zip` from the **signed + notarized + stapled**
35+
`.app` (a `ditto` after `make-dmg.sh`'s signing step) and publish it on the release, plus its
36+
`shasum -a 256`. The `.dmg` stays — it remains the fresh-install path; the `.zip` is update-only.
37+
2. **Feed asset resolution.** `EditorReleaseFeed#fetch_release` currently returns `url: rel["html_url"]`
38+
(the release page) and `sha256hash: nil`. It must select the **right asset** from `rel["assets"]` by
39+
arch and return its `browser_download_url` + the real hash.
40+
3. **Arch mapping.** Feed targets are `darwin-arm64` and `darwin` (Intel). Map to the arm64 / x64 zips
41+
respectively — **never serve a cross-arch zip**.
42+
4. **Lift the guard.** Set `LEVELCODE_UPDATE_FEED_SIGNED=1` on Elastic Beanstalk — **only after 1–3**.
43+
5. **Notify-only Download button.** `extensions/levelcode-updater/extension.js:96` is
44+
`feed.url || product.downloadUrl || base`. Once `feed.url` is a raw `.zip`, that button would hand
45+
users a zip instead of the release page. Reorder to prefer `product.downloadUrl` / the release page.
46+
47+
## Slices
48+
49+
**S1 — publish the signed zip (client).** Add the `ditto` + `shasum` step to `make-dmg.sh` (or a
50+
`make-update-zip.sh`), update `docs/RELEASING.md`, and upload `LevelCode-<arch>.app.zip` with the dmg.
51+
*Ship this alone first — it is inert until the feed points at it.*
52+
53+
**S2 — serve it (server).** Teach `EditorReleaseFeed` to pick the arch-matched asset + hash. Guard stays
54+
on, so behaviour is unchanged; assert the new shape in `spec/requests/api/updates_spec.rb`.
55+
56+
**S3 — extension URL fix.** Reorder the Download preference so it never opens a raw zip.
57+
58+
**S4 — flip the flag + verify.** Set `LEVELCODE_UPDATE_FEED_SIGNED=1`, then run the end-to-end test below.
59+
60+
## Risks (the ones that actually bite)
61+
62+
- **Sequencing.** Flipping the flag before S1–S2 makes things *worse* — Squirrel would download a web
63+
page and fail loudly. S4 must be last.
64+
- **Signing-identity continuity.** Squirrel.Mac refuses an update whose Developer ID doesn't match the
65+
running app. **Rotating or changing the signing cert breaks auto-update for every installed build**,
66+
with no in-app recovery — those users must re-download manually. Treat the identity as long-lived.
67+
- **No staged rollout.** Publishing a release auto-installs for everyone on the next check. The rollback
68+
lever is `LEVELCODE_UPDATE_FEED` (pin the previous commit) — but installs that already updated are
69+
*not* reverted. Consider a canary/percentage gate before this is a large install base.
70+
- **Unverifiable by inspection.** Auto-update can only be proven by actually doing it on a real Mac
71+
(install N, publish N+1, watch the swap). Budget a real test cycle, not a code review.
72+
- **Stapling must survive the zip.** `ditto --sequesterRsrc --keepParent` preserves the stapled ticket;
73+
re-zipping with `zip(1)` can drop extended attributes. Keep using `ditto`.
74+
- **Notarization latency.** Apple's notarization is minutes, occasionally longer — the zip must be cut
75+
*after* `notarize-app` completes, or you publish an unstapled app.
76+
77+
## Exit test
78+
79+
1. Install **N** (e.g. v0.7.2) from the dmg, confirm `About` shows its commit.
80+
2. Publish **N+1** with the signed zip attached and the feed serving it.
81+
3. In N: **Check for Updates…** → it offers, downloads, and **relaunches into N+1**; `About` shows the
82+
new commit. No Gatekeeper prompt.
83+
4. Confirm the Intel build receives the x64 zip (not arm64).
84+
5. Pin `LEVELCODE_UPDATE_FEED` back to N's commit → a fresh N+1 install reports "up to date"
85+
(proves the rollback lever).
86+
87+
## Not doing (explicitly)
88+
89+
- Windows/Linux feeds — `EditorReleaseFeed::TARGETS` is macOS-only by design; announcing a build that
90+
doesn't exist is worse than silence.
91+
- Delta updates. Full-zip replacement is fine at this size.
92+
- Auto-update for the notify-only extension — it stays notify-only by design.

‎docs/RELEASING.md‎

Lines changed: 29 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -81,16 +81,36 @@ Build **both architectures** on matching hardware (Apple silicon → `arm64`, In
8181

8282
```bash
8383
gh release create v0.1.0 --title "LevelCode v0.1.0" --notes "First public build. …" \
84-
LevelCode-arm64.dmg LevelCode-x64.dmg
84+
LevelCode-arm64.dmg LevelCode-x64.dmg \
85+
LevelCode-arm64.app.zip LevelCode-x64.app.zip
8586
```
87+
Upload **both kinds**: the `.dmg` is what humans install; the `.app.zip` is what the built-in updater
88+
installs (Squirrel takes a zip, never a dmg). See §5.
8689
Stable URL: `https://github.com/levelcodeai/levelcode/releases/latest/download/LevelCode-arm64.dmg` — link it
8790
from **levelcode.ai/download**.
8891

89-
## 5. Point the update feed at the release
92+
## 5. The update feed
9093

91-
The notify-only updater (`extensions/levelcode-updater`) polls a feed from `tools/update-server`. After
92-
publishing, update the feed's release entry (version + the release-asset URLs above) so running installs
93-
see the new version. Keep the feed version in lockstep with the tag.
94+
Publishing the GitHub release **is** the announcement — `Levelcode::EditorReleaseFeed` (thin.ly) reads
95+
`releases/latest` and serves `/api/update/{target}/{quality}/{commit}`. There is no feed file to
96+
hand-maintain per release.
97+
98+
Two assets, **not** interchangeable:
99+
100+
| Asset | Consumer |
101+
| --- | --- |
102+
| `LevelCode-<arch>.dmg` | Humans — fresh install, drag to Applications. |
103+
| `LevelCode-<arch>.app.zip` | The built-in **Squirrel** updater — it installs from a zip, never a dmg. |
104+
105+
`make-dmg.sh` emits the `.app.zip` (+ a `.sha256`) **only on the Developer-ID path**, because Squirrel
106+
refuses an update whose signing identity doesn't match the running app — an ad-hoc build must never be
107+
served as an update.
108+
109+
`LEVELCODE_UPDATE_FEED` (env JSON on the server) overrides the GitHub lookup and is the **rollback pin**:
110+
point it at the previous commit to stop a bad release propagating. Note it can't un-update anyone who
111+
already took the release.
112+
113+
Full contract, rollout order, and risks: **`docs/AUTO-UPDATE.md`**.
94114

95115
## 6. Troubleshooting *(the ones that actually bit us are marked ⚑)*
96116

@@ -130,11 +150,12 @@ gh release download v0.1.0 --pattern 'UNSIGNED-*.app.zip'
130150
for A in arm64 x64; do
131151
rm -rf "VSCode-darwin-$A" && ditto -x -k "UNSIGNED-LevelCode-$A.app.zip" "VSCode-darwin-$A"
132152
CODESIGN_IDENTITY="Developer ID Application: SERGII DEMIANCHUK (AJ27Y4Z2HS)" \
133-
NOTARY_PROFILE=levelcode-notary ./scripts/make-dmg.sh "$A" # → LevelCode-$A.dmg (signed+notarized+stapled)
153+
NOTARY_PROFILE=levelcode-notary ./scripts/make-dmg.sh "$A" # → LevelCode-$A.dmg + LevelCode-$A.app.zip
134154
done
135155

136-
# 3. Verify (§3), then attach the dmgs, drop the unsigned zips, and publish
137-
gh release upload v0.1.0 LevelCode-arm64.dmg LevelCode-x64.dmg
156+
# 3. Verify (§3), then attach the dmgs AND the update zips, drop the unsigned zips, and publish
157+
gh release upload v0.1.0 LevelCode-arm64.dmg LevelCode-x64.dmg \
158+
LevelCode-arm64.app.zip LevelCode-x64.app.zip
138159
# `gh release delete-asset` takes ONE asset per call — drop each unsigned zip separately (`-y` skips the prompt).
139160
gh release delete-asset v0.1.0 UNSIGNED-LevelCode-arm64.app.zip -y
140161
gh release delete-asset v0.1.0 UNSIGNED-LevelCode-x64.app.zip -y

‎scripts/make-dmg.sh‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,8 @@
1111
# 2. Ad-hoc code-signs it. arm64 macOS refuses to launch *unsigned* binaries at all,
1212
# so even for personal use the app must carry at least an ad-hoc signature.
1313
# 3. Builds a compressed .dmg containing the app + an /Applications symlink.
14+
# 4. On the Developer ID path only, also emits LevelCode-<arch>.app.zip (+ .sha256) — the
15+
# auto-update feed asset the built-in Squirrel updater installs. See docs/AUTO-UPDATE.md.
1416
#
1517
# The result is UNNOTARIZED. On another Mac, Gatekeeper will still warn on first launch:
1618
# - Right-click the app > Open (once), OR
@@ -98,11 +100,28 @@ if [ "$NOTARIZE" = "1" ]; then
98100
"$SCRIPT_DIR/notarize.sh" submit "$DMG_OUT"
99101
fi
100102

103+
# 5. Squirrel update asset — a .zip of the SIGNED + NOTARIZED + STAPLED .app.
104+
# The built-in updater (Squirrel.Mac) installs from a .zip, never a .dmg, and refuses an update whose
105+
# Developer ID doesn't match the running app — so this is produced ONLY on the signed path; an ad-hoc
106+
# build must never masquerade as an update asset. Use `ditto` (not `zip`): it preserves the stapled
107+
# notarization ticket, so the updated app still validates offline. Feed + rollout: docs/AUTO-UPDATE.md.
108+
ZIP_OUT=""
109+
if [ "$NOTARIZE" = "1" ]; then
110+
ZIP_OUT="$ROOT_DIR/LevelCode-$ARCH.app.zip"
111+
echo "[make-dmg] Creating the signed update asset (Squirrel .zip) …"
112+
rm -f "$ZIP_OUT" "$ZIP_OUT.sha256"
113+
ditto -c -k --sequesterRsrc --keepParent "$APP" "$ZIP_OUT"
114+
shasum -a 256 "$ZIP_OUT" | cut -d' ' -f1 > "$ZIP_OUT.sha256"
115+
fi
116+
101117
SIZE="$(du -sh "$DMG_OUT" | cut -f1)"
102118
echo "[make-dmg] Done."
103119
echo "[make-dmg] Output: $DMG_OUT ($SIZE)"
104120
if [ "$NOTARIZE" = "1" ]; then
105121
echo "[make-dmg] Signed + notarized — upload it; users just open the dmg and drag to Applications."
122+
echo "[make-dmg] Update asset: $ZIP_OUT ($(du -sh "$ZIP_OUT" | cut -f1))"
123+
echo "[make-dmg] sha256: $(cat "$ZIP_OUT.sha256")"
124+
echo "[make-dmg] Upload BOTH: the .dmg (fresh installs) and the .app.zip (auto-update feed)."
106125
else
107126
echo "[make-dmg] Upload this single file. On the other Mac: open the dmg, drag LevelCode to"
108127
echo "[make-dmg] Applications, then right-click > Open the first time (it's unnotarized)."

0 commit comments

Comments
 (0)