407 lines
22 KiB
Markdown
407 lines
22 KiB
Markdown
# Releases and updates
|
|
|
|
Shift's update channel is this repository. There is no update server, no object
|
|
storage, and no release service to configure: the installers and a small manifest are
|
|
pushed to a git branch, and a running copy reads that branch over HTTPS.
|
|
|
|
## The channel
|
|
|
|
An orphan branch named `releases` holds exactly one release:
|
|
|
|
```text
|
|
releases/
|
|
├── shift-update.json
|
|
├── shift-update.sig
|
|
├── Shift-0.1.13-macOS-universal.dmg
|
|
└── Shift-Setup-0.1.13-win-x64.exe
|
|
```
|
|
|
|
`shift-update.json` names the version and, per platform, the artifact file, its size in
|
|
bytes and its SHA256:
|
|
|
|
```json
|
|
{
|
|
"schema": 1,
|
|
"version": "0.1.13",
|
|
"date": "2026-10-26",
|
|
"notes": "",
|
|
"artifacts": {
|
|
"macos": { "file": "Shift-0.1.13-macOS-universal.dmg", "sha256": "…", "size": 0 },
|
|
"windows": { "file": "Shift-Setup-0.1.13-win-x64.exe", "sha256": "…", "size": 0 }
|
|
}
|
|
}
|
|
```
|
|
|
|
Artifact names are restricted to ASCII letters, digits, `.`, `-` and `_`; path
|
|
separators, `..`, spaces and shell metacharacters are rejected. The app also
|
|
refuses a manifest over 256 KiB. These checks keep malformed manifest data out
|
|
of download paths and out of the native handoff arguments.
|
|
|
|
## Supported release targets
|
|
|
|
**Shift ships two installers: macOS (universal) and Windows x64.** That is a scope decision,
|
|
not a code limit, and it decides what the channel may contain:
|
|
|
|
| Key | Shipped | Notes |
|
|
| --- | --- | --- |
|
|
| `macos` | yes | One universal bundle, Apple silicon and Intel, shipped as a DMG. Verified on a fresh machine by dragging it to /Applications — see "macOS packaging" |
|
|
| `windows` | yes | x64, which is also what an ARM machine falls back to |
|
|
| `windows-arm64` | no | Runtime compatibility only: Windows on ARM installs the x64 package through `windows` |
|
|
| `linux` | no | Build target, not a product; see below |
|
|
|
|
The incident history, failure signatures and non-negotiable implementation constraints
|
|
behind the current Drop, conversion and macOS packaging behaviour are recorded in
|
|
[`ENGINEERING-NOTES.md`](ENGINEERING-NOTES.md). Read the relevant section before changing
|
|
those paths; this release guide defines the channel, while the engineering ledger explains
|
|
why the current shape must not be simplified back into an earlier failure.
|
|
|
|
Keys are platform, then platform and architecture where they differ. A build picks the
|
|
first key its own architecture matches and never crosses operating systems:
|
|
|
|
| Running on | Keys tried, in order |
|
|
| --- | --- |
|
|
| macOS (Apple silicon or Intel) | `macos` |
|
|
| Windows x64 | `windows` |
|
|
| Windows ARM64 | `windows-arm64`, then `windows` |
|
|
| Linux | `linux` |
|
|
|
|
The ARM64 fallback to `windows` is deliberate: Windows on ARM runs x64 binaries under
|
|
emulation, so a channel that only carries x64 keeps serving ARM machines exactly as it did
|
|
before the ARM build existed. `artifact_keys_for` and `select_artifact` in
|
|
`src-tauri/src/update.rs` hold that ladder and are tested directly, so the rule is fixed
|
|
by a test rather than by a comment.
|
|
|
|
The branch is rebuilt as a fresh root commit on every publish and force-pushed, so it
|
|
never accumulates gigabytes of installer history while `main` stays clean.
|
|
|
|
## macOS packaging
|
|
|
|
Shift builds are **ad-hoc signed** (`signingIdentity: "-"` in `tauri.conf.json`) and are
|
|
**not notarized** — notarization needs an Apple Developer ID account, which this project
|
|
does not have. Gatekeeper therefore cannot vouch for any Shift build, and what a fresh
|
|
machine says depends on how the binary is signed:
|
|
|
|
| Signing | What a fresh machine says |
|
|
| --- | --- |
|
|
| Ad-hoc (`Signature=adhoc`) — **current** | "cannot be opened because it is from an unidentified developer", and the box offers a way through: Cancel, then right-click → 打开, or 允许 in 系统设置 → 隐私与安全性 |
|
|
| Self-signed certificate | "cannot be opened because it is damaged" / reported as malware, with **only 移至废纸篓** — no override, no pane entry to approve |
|
|
| Developer ID + notarized | Opens on double-click, no prompt |
|
|
|
|
The middle row is what a release shipped with, and it is a trap because it looks healthy
|
|
locally: `codesign` reports `valid on disk` and `satisfies its Designated Requirement`, and
|
|
`spctl` accepts it on the build host. The certificate ("Shift Local Signing") is self-issued,
|
|
`CA:FALSE`, and present in only that one Mac's keychain, so on any other machine it cannot
|
|
chain to a trusted root — and an unchainable signature on a quarantined download is a hard
|
|
refusal rather than a prompt.
|
|
|
|
One correction worth keeping, because the obvious story is wrong: every DMG this channel has
|
|
ever published carries that same `Authority=Shift Local Signing`, including the earliest 0.1.0
|
|
ones, because Tauri picks a keychain identity itself when `signingIdentity` is unset. So
|
|
"older builds were ad-hoc" is **not** why one machine accepted them — a machine that had been
|
|
shown the app before may already trust the certificate, and Gatekeeper's own heuristics have
|
|
changed across macOS versions. What is verified is the direction of the fix: an ad-hoc binary
|
|
is reported as an unidentified developer with a way through, which is the behaviour this
|
|
project wants, and no release is worse off for losing a certificate no other Mac can check.
|
|
Reusing that identity again would mean installing it **and trusting it** on every machine,
|
|
which is not something to ask of a user.
|
|
|
|
So: ad-hoc, and one container. The channel ships **`Shift-<version>-macOS-universal.dmg`** and nothing
|
|
else on macOS — the earlier `.pkg` companion was dropped after the DMG was verified to work
|
|
on a fresh machine, and one file per platform is less to keep straight.
|
|
|
|
| Situation | What happens |
|
|
| --- | --- |
|
|
| A machine installing Shift for the first time | Double-click the DMG, drag `Shift.app` to /Applications. The app keeps the browser's quarantine flag, so the **first launch** needs the one approval above: right-click → 打开, or 允许 in 系统设置 → 隐私与安全性. Every launch after that is normal. |
|
|
| An installed Shift updating itself | `update_install`'s handoff downloads the DMG, mounts it with `hdiutil`, copies the bundle out and drops the quarantine flag. Shift's own downloader sets no quarantine flag (`curl` sets none, and the handoff strips it anyway), so **in-app updates never prompt**. |
|
|
|
|
The `macos` manifest key is a DMG for the same reason: the in-app handoff mounts the image,
|
|
so pointing the key at a package would break every in-app update. That was the one real
|
|
constraint the container had to satisfy, and a DMG satisfies it.
|
|
|
|
The retired `.pkg` packaging script has been removed. The DMG is the only macOS
|
|
container in the release pipeline.
|
|
|
|
### macOS release gate
|
|
|
|
Every macOS release must pass all of these before it goes into `artifacts/`:
|
|
|
|
1. Run `pnpm mac:release`. It rebuilds the universal Swift sidecars, builds the app
|
|
and DMG, verifies both, and copies the result to the versioned release name.
|
|
2. Run `codesign --verify --deep --strict` on `Shift.app`, and confirm
|
|
`codesign -dv --verbose=2` reports `Signature=adhoc`. A local certificate name here is
|
|
a release blocker, not a stronger signature.
|
|
3. Run `hdiutil verify artifacts/Shift-<version>-macOS-universal.dmg` and verify `SHA256SUMS.txt` after copying
|
|
the final artifact into `artifacts/`.
|
|
4. Confirm the release contains no `.pkg`, and that the manifest's `macos` entry points at
|
|
the DMG. The in-app helper mounts that exact container with `hdiutil`.
|
|
5. Transfer the DMG to a different Mac, preferably one that has never installed Shift.
|
|
Download the final artifact through a browser from the release feed when possible so the
|
|
quarantine flag matches the real user path; if a USB or AirDrop transfer is used, confirm
|
|
the quarantine attribute is present, otherwise Gatekeeper was not exercised. Drag
|
|
`Shift.app` to `/Applications`, approve the first launch once, and verify the version.
|
|
6. On that same machine, open Drop and confirm another Shift peer appears and stays in the
|
|
list. A packaging or signing change can invalidate Local Network approval even when the
|
|
app itself starts correctly.
|
|
7. For an update release, install the previous version on that machine and run the in-app
|
|
update once. It must restart on the new version without a Gatekeeper prompt.
|
|
|
|
The build host opening its own DMG proves neither cross-machine installation nor the
|
|
quarantine behaviour. Step 5 is the hard release gate. The full incident record and the
|
|
manual Drop matrix are in [`ENGINEERING-NOTES.md`](ENGINEERING-NOTES.md).
|
|
|
|
Closing this for good means an Apple Developer ID: `Developer ID Application` +
|
|
`notarytool` + `stapler staple`. Then the DMG opens on double-click with no pane to visit,
|
|
and the privacy grants keyed to that identity — Screen Recording, and Local Network, which
|
|
is what device discovery needs — stop resetting between builds. That reset is not
|
|
theoretical: a 0.1.4 user found the device list empty after upgrading, with nothing in the
|
|
UI to say why.
|
|
|
|
## Publishing
|
|
|
|
```bash
|
|
pnpm mac:release
|
|
scripts/build-windows-release.sh
|
|
printf 'Fixes the ring on external displays.\n' > /tmp/notes.md
|
|
scripts/publish-release.sh --notes /tmp/notes.md # hash, commit, push
|
|
```
|
|
|
|
`scripts/publish-release.sh` hashes every file in `artifacts/`, builds the manifest,
|
|
writes the tree with git plumbing (`update-index` → `write-tree` → `commit-tree` →
|
|
`update-ref`, through a temporary `GIT_INDEX_FILE` so the working tree is untouched) and
|
|
force-pushes `releases`. The manifest and the pushed bytes cannot disagree, because the
|
|
same Python pass that walks the files produces both.
|
|
|
|
| Flag | Effect |
|
|
| --- | --- |
|
|
| `--notes FILE` | Release notes shown in the Updates panel |
|
|
| `--key FILE` | Sign the manifest with this ed25519 key (`SHIFT_RELEASE_KEY` also works) |
|
|
| `--dry-run` | Print the manifest and the tree that would be pushed; write nothing |
|
|
| `--no-push` | Commit locally on `releases` but leave the remote alone |
|
|
| `--branch NAME` | Publish to another channel instead of `releases` |
|
|
|
|
Recognised installers are exactly `Shift-<version>-macOS-universal.dmg` (macOS) and
|
|
`Shift-Setup-<version>-win-x64.exe` (Windows). Publishing fails if either is missing,
|
|
or if any other `.dmg`, `.exe`, `.msi`, `.pkg`, `.zip`, AppImage or deb remains in
|
|
`artifacts/`. `SHA256SUMS.txt`, the two platform notes and `README-macOS-universal.txt`
|
|
travel with the branch as supporting files, never as installers. Dotfiles and an old
|
|
manifest are skipped.
|
|
|
|
`README-macOS-universal.txt` is tracked in the repository as well as pushed to the channel,
|
|
so the scheme is documented where a contributor reads it and not only next to a build
|
|
product. Every claim in it was checked against the shipped artifacts: the bundle inside the
|
|
published DMG is `Signature=adhoc`, and `shasum -a 256 -c SHA256SUMS.txt` passes on the
|
|
published set.
|
|
|
|
The Windows command cross-compiles one target, checks the PE machine field (`0x8664`)
|
|
and gates the installer to x64:
|
|
|
|
```bash
|
|
scripts/build-windows-release.sh
|
|
scripts/build-windows-release.sh --skip-build
|
|
```
|
|
|
|
## Signing the channel
|
|
|
|
Integrity says the download matches the manifest; authenticity says the manifest came
|
|
from you. `scripts/release-key.py` closes that gap with one ed25519 key.
|
|
|
|
```bash
|
|
scripts/release-key.py keygen ~/.config/shift-release/release.ed25519
|
|
# -> prints the hex public key to bake into the build
|
|
|
|
export SHIFT_RELEASE_KEY=~/.config/shift-release/release.ed25519
|
|
pnpm mac:release # macOS universal DMG
|
|
scripts/build-windows-release.sh # Windows x64 installer
|
|
scripts/publish-release.sh --key "$SHIFT_RELEASE_KEY"
|
|
```
|
|
|
|
Give the release build `SHIFT_UPDATE_PUBKEY` (the hex key) and it can verify the feed; give
|
|
it `SHIFT_RELEASE_KEY` (the private key) and both release scripts derive the public key from
|
|
it, so a build can never be packaged with a key that does not match the signature
|
|
`publish-release.sh --key` produces. Without either, the script prints
|
|
`no release key: this build will report the feed as unsigned` rather than letting it pass
|
|
for a quieter log.
|
|
|
|
The signature is **detached**: `shift-update.sig` holds base64 over the manifest's exact
|
|
bytes, so verification needs no JSON canonicalisation rules and the manifest's formatting
|
|
stays free to change. It is fetched from the directory that already holds the manifest, so
|
|
a staging feed needs only its own manifest plus signature — a fork never configures a
|
|
second URL.
|
|
|
|
| Build | Feed | Result |
|
|
| --- | --- | --- |
|
|
| Key baked | signature verifies | update offered, panel says the signature was verified |
|
|
| Key baked | signature missing or wrong | check fails with that reason; nothing is offered |
|
|
| No key | any | integrity gate only; panel says this build cannot verify a signature |
|
|
|
|
The key is the one secret in this design. Losing it means publishing a new app build with
|
|
a new baked key; leaking it means an attacker can publish anything to the channel, exactly
|
|
as leaking push access to `releases` already does today. Keep it outside the repository —
|
|
`~/.config/shift-release/` is where the local publishing machine keeps it.
|
|
|
|
`scripts/release-key.py` treats a file ending in `.pub` as an ed25519 public
|
|
key and every other path as the 32-byte private key. `keygen` writes the private
|
|
key (`release.ed25519`, mode 0600) and its public companion (`release.pub`). Keep
|
|
the private key out of CI logs and do not rename the public file to a non-`.pub`
|
|
name when using `pubkey`.
|
|
|
|
## Where a build looks for updates
|
|
|
|
`src-tauri/build.rs` derives the feed from the `origin` remote at build time:
|
|
|
|
| Remote | Feed URL |
|
|
| --- | --- |
|
|
| Gitea / Forgejo | `https://host/owner/repo/raw/branch/releases/shift-update.json` |
|
|
| GitHub | `https://github.com/owner/repo/raw/releases/shift-update.json` |
|
|
| GitLab | `https://gitlab.example/owner/repo/-/raw/releases/shift-update.json` |
|
|
|
|
Two overrides exist, and neither needs a rebuild of the frontend:
|
|
|
|
- `SHIFT_UPDATE_PUBKEY` at build time bakes in the release key; anything that is not 32
|
|
bytes of hex fails the build rather than silently producing an updater that trusts the
|
|
feed anyway. A key that parses but is not a curve point is a runtime error, never a
|
|
quiet downgrade to "no key".
|
|
- `SHIFT_UPDATE_URL` at build time bakes a different feed into the binary.
|
|
- `SHIFT_UPDATE_URL` in the environment of a running copy wins over the baked value,
|
|
which is how a fork or a staging branch is tested.
|
|
|
|
A source tree with no remote builds an updater that reports "no feed" rather than
|
|
guessing at one.
|
|
|
|
## What the app does with it
|
|
|
|
1. Once a day, at startup (and on demand from Settings → **Updates**), the manifest is
|
|
fetched with the system HTTP client — `/usr/bin/curl` on macOS and Linux,
|
|
`Invoke-WebRequest` on Windows. The day of the last probe is stored in `settings.json`,
|
|
so restarts cannot spend the day's check twice.
|
|
2. Versions are compared with semver rules, prereleases included: `0.2.0-alpha` sorts
|
|
below `0.2.0`, so a test build does not offer to downgrade itself.
|
|
3. Download writes into a temp folder, then two gates run: the byte length must equal the
|
|
manifest's `size`, and the recomputed SHA256 must equal the manifest's `sha256`. Both
|
|
checks run again immediately before the handoff. A mismatch deletes the file and
|
|
reports the error, so a truncated or swapped installer never reaches the installer
|
|
step.
|
|
4. **Install & relaunch** applies the verified artifact and restarts Shift on it, as
|
|
described in the next section; **Discard** removes the downloaded artifact as well as
|
|
the update status. When an update is available the tray menu gains a row that opens
|
|
Settings on the Updates tab.
|
|
|
|
Manifest `schema` is checked; this build accepts exactly `1` and refuses anything else
|
|
instead of being parsed optimistically. Unknown platform keys are ignored, so the
|
|
manifest can name a platform an older app has never heard of. The Updates panel always
|
|
states which of the two properties the current feed satisfies, so an unsigned channel
|
|
never looks signed.
|
|
|
|
## Applying an update
|
|
|
|
Neither operating system lets a running program replace its own executable, so the work
|
|
belongs to a helper that outlives the app. `update_install` writes a script into the
|
|
download folder, starts it detached, and exits about half a second later; the script waits
|
|
for that pid to disappear and only then touches the installed copy.
|
|
|
|
| Platform | What the helper does |
|
|
| --- | --- |
|
|
| macOS | Mounts the downloaded `.dmg`, `ditto`s the new bundle next to the old one, swaps them with two `mv` calls, removes the quarantine flag, detaches the image, and `open`s the result |
|
|
| Windows | Waits for `shift.exe` to leave the process table, runs the installer with `/S`, then starts the `shift.exe` the installer wrote |
|
|
| Linux, and a macOS binary run outside a bundle | Nothing is replaced; the artifact is opened instead, and the panel says so |
|
|
|
|
Both scripts are written so a failure cannot end with Shift simply closed: every macOS
|
|
failure path still `open`s the bundle it had, and the swap is `move aside, move in`, so a
|
|
copy that fails halfway leaves the previous version where it was. The scripts themselves
|
|
are fixed constants; the pid, installer, bundle and log paths arrive through process
|
|
arguments or environment variables, never interpolated into shell or batch source. The
|
|
Windows launcher also keeps the outer quote layer that `cmd.exe /C` would otherwise strip
|
|
from a script path containing spaces. Before the handoff starts, macOS
|
|
writes a probe file next to the bundle — a root-owned copy in `/Applications` is reported
|
|
as "open the downloaded installer yourself" rather than quietly quitting on an update
|
|
that could not be applied.
|
|
|
|
The Windows installer is the same one a user runs by hand, so the update path cannot drift
|
|
from the manual one. Because the silent install comes from Shift itself, `${Silent}` skips
|
|
the interactive "Shift is running, close it?" box and the WebView2 warning: the app
|
|
already told the user it is about to restart, and a box nobody can answer would abort or
|
|
hang the update.
|
|
|
|
This is not a delta update and not a signature check on the running binary: the same
|
|
SHA256 gate that guards a manual install is the only integrity gate, and the manifest
|
|
signature rules in "Signing the channel" apply unchanged.
|
|
|
|
Replacing the bundle gives it a new code-signing hash, and macOS keys permissions such as
|
|
Screen Recording to that hash. A release signed with the same identity as the copy it
|
|
replaces normally keeps its approvals; a locally signed build, where every build has its
|
|
own identity, can ask again after an update. That is the same consequence a manual
|
|
reinstall has, and it is why the notarized-build item in the roadmap is worth closing.
|
|
|
|
## Trust boundary
|
|
|
|
Two properties, two mechanisms:
|
|
|
|
- **Integrity of the installer** — byte length plus recomputed SHA256 against the
|
|
manifest. Always enforced, in every build.
|
|
- **Authenticity of the manifest** — a detached ed25519 signature verified against a baked
|
|
public key. Enforced in every build that was compiled with `SHIFT_UPDATE_PUBKEY`.
|
|
|
|
A build without a key falls back to the weaker trust it had before signing existed: the
|
|
HTTPS connection to the forge plus whoever can push to `releases`. That is the only
|
|
remaining gap for such a build, and the panel says so out loud. Developer ID signing plus
|
|
notarization for the macOS package — which macOS requires for downloaded apps regardless —
|
|
is still open and tracked in `docs/ROADMAP.md` under M5.
|
|
|
|
```bash
|
|
scripts/release-key.py verify ~/.config/shift-release/release.pub \
|
|
manifest.json manifest.sig # check a channel by hand
|
|
```
|
|
|
|
## Verifying a channel by hand
|
|
|
|
```bash
|
|
SHIFT_UPDATE_URL="https://host/owner/repo/raw/branch/releases/shift-update.json" \
|
|
cargo test --lib update:: -- --ignored # from src-tauri/
|
|
```
|
|
|
|
```bash
|
|
cargo test --lib update:: -- --ignored # unsigned build: integrity only
|
|
SHIFT_UPDATE_PUBKEY=<hex> cargo test --lib update:: -- --ignored
|
|
```
|
|
|
|
The test fetches the real feed, checks the manifest signature when the build carries a
|
|
key, then downloads the artifact for this platform and architecture and checks size and
|
|
hash against what is on disk. A baked key that is valid but not the publisher's fails the
|
|
test, which is the proof that the check is real and not a pass-through.
|
|
|
|
## State of the published channel
|
|
|
|
This section is a historical audit of the published channel at the time it was
|
|
performed. It is not a claim that the current `releases` branch still contains
|
|
this version or that CI produced it. Re-run the verification below before using
|
|
these numbers in release notes.
|
|
|
|
Version **0.1.7**, checked by downloading each artifact back from the raw endpoint rather
|
|
than trusting the local copy:
|
|
|
|
| Key | Artifact | Verified from the remote |
|
|
| --- | --- | --- |
|
|
| `macos` | `Shift-macOS-universal.dmg` (55,585,331 B) | bytes downloaded, SHA256 matches the manifest |
|
|
| `windows` | `Shift-Setup-0.1.7-win-x64.exe` (24,514,334 B) | bytes downloaded, SHA256 matches the manifest |
|
|
| `windows-arm64` | not published | by choice — see "Supported release targets" |
|
|
| `linux` | not published | by choice: Linux is a build target here, not a shipped product |
|
|
|
|
The retired `Shift-macOS-universal.pkg` left the branch with this publish: the branch is
|
|
rebuilt from `artifacts/` on every run, so dropping it from the build was enough. macOS now
|
|
ships the one container ("macOS packaging").
|
|
|
|
`shift-update.sig` verifies over the manifest's exact bytes against the key baked into both
|
|
artifacts. The channel's home is derived from `origin` at build time, and this forge is
|
|
Gitea, so the raw form is `/raw/branch/releases/`.
|
|
|
|
Both artifacts carry the key and the feed URL, which is what makes an in-app upgrade
|
|
possible at all: a build whose binary predates those constants reports "this build has no
|
|
feed" and can never see the channel, however new it is.
|
|
|
|
The workflow defines separate macOS, Windows and Linux jobs, but this audit did
|
|
not record a linked CI run. Treat the local commands in `CONTRIBUTING.md` as the
|
|
release gate unless a green run is attached to the release.
|
|
|
|
A Linux release would slot in under the `linux` key with no code change — `artifact_keys_for`
|
|
already answers `linux` for that host — so publishing one is a build task, not a feature.
|