Self-Update and Releases

The self-update subcommand fetches the latest release from GitHub, verifies its build provenance with keyless Sigstore attestation, and atomically replaces the running binary. It is implemented in wcore-cli/src/self_update.rs.

Basic usage

wayland-core self-update             # check and install if newer
wayland-core self-update --check-only  # print version diff, do not write to disk

--check-only prints the current and latest version strings and exits without touching the filesystem:

current: v0.12.25
latest:  v0.12.25
already up to date.

If you are already on the latest version the command prints already up to date. and exits cleanly.

What the update process does

Fetch release metadata. The command issues a GET to https://api.github.com/repos/FerroxLabs/wayland-core/releases/latest. The release repo is a compile-time constant (RELEASES_REPO = "FerroxLabs/wayland-core") so a misconfigured workspace cannot redirect updates to a different repository. The HTTP client is wcore_egress::EgressClient (not raw reqwest) so the request passes through the egress policy.

Resolve the archive name. The release packages one archive per target. The archive name is derived from the host OS and architecture and matches the build matrix in release.yml. Windows targets ship a .zip; every other target ships a .tar.gz:

Host	Archive
macOS aarch64	`wayland-core-vX.Y.Z-aarch64-apple-darwin.tar.gz`
macOS x86_64	`wayland-core-vX.Y.Z-x86_64-apple-darwin.tar.gz`
Linux x86_64	`wayland-core-vX.Y.Z-x86_64-unknown-linux-gnu.tar.gz`
Linux aarch64	`wayland-core-vX.Y.Z-aarch64-unknown-linux-gnu.tar.gz`
Windows x86_64	`wayland-core-vX.Y.Z-x86_64-pc-windows-msvc.zip`
Windows aarch64	`wayland-core-vX.Y.Z-aarch64-pc-windows-msvc.zip`

Download. The archive is streamed into a temporary directory from the browser_download_url returned by the GitHub API. When Content-Length is present, the downloaded byte count is verified against it and a size mismatch is a hard error. Verification then runs over whatever bytes were written regardless.
Verify build provenance (keyless). Before extracting or swapping anything, the command verifies the archive’s Sigstore build-provenance attestation by shelling out to the GitHub CLI:
```
gh attestation verify <archive> --repo FerroxLabs/wayland-core
```
Releases are signed keylessly through GitHub OIDC and Sigstore (actions/attest-build-provenance in the release workflow). There is no long-lived signing key to pin or rotate. gh checks the attestation against the pinned source repo and the public Sigstore transparency log, so an archive that was not built by FerroxLabs/wayland-core’s release workflow fails verification and is rejected before extraction. The gh process is spawned in argv mode (no shell), so archive-path metacharacters are never interpreted.

Verification fails closed. If gh is not installed, the command refuses to install rather than skipping the check, and prints guidance to install the GitHub CLI from https://cli.github.com or to update via npm instead (the npm package is itself provenance-backed).
Extract. Only after provenance passes does the command extract the wayland-core (or wayland-core.exe) binary from the verified archive. Both .tar.gz and .zip are supported, with a zip-slip guard that rejects any entry whose path escapes the destination directory.
Atomic swap. On Unix, the new binary is chmod 755 then swapped in with self_replace::self_replace, which performs a POSIX rename. On Windows it uses MoveFileExW and handles the running-exe lock. The swap is atomic: either the new binary is in place or the old one remains.

Why keyless provenance, not a pinned key

An earlier design pinned an ed25519 release key and verified a separate .sig file over the binary. That scheme was never operational: the binary shipped an all-zero placeholder key and the release pipeline never produced .sig files, so self-update could not have worked and the design carried long-lived-key custody debt. The current mechanism removes the signing key entirely. Trust is anchored in GitHub’s OIDC identity and the Sigstore transparency log rather than in a key that someone has to guard and rotate.

404 handling

If the repository exists but has no releases yet, the GitHub API returns HTTP 404. The command handles this as Ok(None) and prints a clean message rather than treating it as a broken-repo error:

current: v0.12.25
latest:  no releases published yet on FerroxLabs/wayland-core

Any other non-2xx response is a hard error.

Release channels

There is currently one release channel: latest on the FerroxLabs/wayland-core GitHub repository. Release tags have the form vX.Y.Z or vX.Y.Z-wayland-base; the version parser strips both the v prefix and the -wayland-base suffix so the displayed version matches CARGO_PKG_VERSION.

Pre-release and beta channels are not yet wired to the self-update command. To test a specific release, install it manually:

cargo install --git https://github.com/ferroxlabs/wayland-core \
    --tag v0.12.25 wcore-cli

npm installs

If you installed through npm (npm install -g @ferroxlabs/wayland-core), update the same way:

npm install -g @ferroxlabs/wayland-core@latest

The npm package wraps the platform binary; wayland-core self-update also works for npm-installed binaries as long as the binary path is writable by the current user.