Skip to main content
Bach supports two kinds of updates. A newer setup file run over an install updates it in place, with no setup. The second kind lets the installed app find, download and install new versions on its own. This page covers both, how to publish updates from GitHub, what an app can do to update when the user quits, and what survives a closed window or a power cut.

Update by running a newer setup file

Raise version in bach.toml, rebuild with bach build, and hand out the new setup file. Running it over an install updates it:
  • It keeps the install folder, the user’s choices and the user’s data.
  • It removes files the earlier version installed and the new one does not ship, including components the user unticked. The earlier file list comes from the old uninstaller. A file the user changed since it was installed is kept, and so is one a program still holds (the log says which).
  • It starts the option boxes the way the user left them. Unticking one takes the shortcut, PATH entry or autostart away.
  • If anything goes wrong midway, the earlier version stays exactly as it was. Files are unpacked next to their targets first and swapped in together; if one is locked, every move is undone.
  • If the app is running, setup says so and offers “Close and continue”, which asks the app to close the way Windows Update does. It may ask to save first, and nothing is killed.
Keep [app] id (it defaults to name) the same across versions. Changing it makes the update install side by side instead of over the old version.
Running an older setup file over a newer install is refused. The window shows a downgrade page, and a silent run stops with exit code 1 unless you pass --allow-downgrade.

How an installed app knows what is new

The installed app does not guess. It asks one small file, the update feed (latest.json), whose address is baked into every setup file by [updates] in bach.toml. The feed says which version is newest and where to download it:
latest.json
1

You publish

bach build writes the setup file and latest.json next to it. You, or the release workflow, upload both to a place with a fixed address for the feed.
2

The app asks

The scheduled task (every four hours) or your app (uninstall.exe --check-update) fetches the feed and compares its version with the installed version. Only a higher version counts.
3

It downloads

The setup file from url, into the background folder, checked against sha256.
4

It installs

When the app is not running.
There is no server of yours to run: any place that serves two static files over https works. The online installer uses the same feed, so publishing a release updates installed apps and what new users get.

Where to host updates

Publish updates from GitHub

The quickest way is the one-click release workflow that bach init or bach workflow writes into your repository. It raises the version everywhere, builds and publishes: see One-click releases. The steps below are the same thing written by hand.
1

Point bach.toml at your repository

bach.toml
bach init writes this for you in a checkout whose origin is on GitHub. The repository must be public, because the installed app reads the feed without signing in.
2

Add the action to a workflow that runs on tags

.github/workflows/release.yml
3

Push a tag

The tag is the version: v1.4.0 builds the app as 1.4.0, so there is no second place to keep it. The action builds the setup file, writes latest.json and publishes both as a GitHub release.
Installed apps find the release here: GitHub renames uploaded files that have spaces or odd characters, which would break that link. With github set, bach build names the setup file the way GitHub serves it, so My App is built as My-App-Setup-1.4.0.exe. A pre-release (prerelease: true) is not GitHub’s “latest”, so installed apps do not update to it. Publishing a fix for an older line with latest: false keeps them on the newest release. To sign the file, pass sign-command; it runs before the feed is written, so the feed has the signed file’s SHA-256. All inputs are in Automate in CI.

Pick the Bach version

usebach/bach@v0 builds with the newest 0.x release of Bach, @v0.2 with the newest 0.2.x, and @v0.2.1 never moves. A full commit SHA never moves either, and builds with the Bach version in that commit’s Cargo.toml. Add version: to build with another one, like 0.2 or latest. The install scripts take the same through BACH_VERSION.

What the installed app does

With [updates], the install page offers Automatic updates, ticked. Ticked, setup adds a per-user Windows scheduled task, Bach\<app id>, that runs uninstall.exe --auto-update every four hours (spread by up to 20 minutes) and as soon as it can after a time it missed because the PC was off. It needs no administrator rights and runs hidden. Each run:
  1. Reads the feed. A failed read just waits for the next run.
  2. Downloads a newer setup file into %LOCALAPPDATA%\Bach\updates\<app id> and keeps it.
  3. Installs it only when the app is not running. Otherwise it stays ready for the next run.
An update never closes a program somebody is working in. Unticking the box on a later update, and uninstalling, delete the task. Use auto = false to offer the box unticked, or "always" and "never" to decide for the user (see [updates]).

What your app can do

The installed uninstall.exe answers these commands, with or without the scheduled task: To update when the user quits:
1

At start, in the background

2

When the user quits, or picks restart to update

Start this and exit:
These commands are PowerShell. uninstall.exe is a windowed program, so a shell does not wait for it or give you its exit code unless you use Start-Process -Wait -PassThru; from your own app, start it with your language’s process API and wait for it. The download finished while the app was in use, so closing it costs a few seconds. A “Later” button needs no code: leave the update kept, and the next start or the scheduled task takes it. Every update run writes %TEMP%\<app id>-update.log.

Signed feeds

A feed names a download and its SHA-256, and both come from the same host, so whoever controls that host controls the update. A publisher key takes that away. bach feed-key writes a private key to feed-key.private (it never overwrites a file) and prints the line for bach.toml:
bach.toml
bach feed signs each entry with the private key, read from BACH_FEED_KEY (the key) or BACH_FEED_KEY_FILE (a file with the key on its first line). Without it bach feed refuses, and bach build builds but warns that latest.json is unsigned. An installed app whose setup file has the public key accepts only entries with a valid signature, whichever feed or mirror served them. A changed link, SHA-256, size, rollout or patch, an unsigned entry or one signed by another key is ignored. Release notes are not signed. Apps without a public_key keep working with unsigned feeds. An app trusts only the keys its own setup file carries, so keep the private key safe. If you must change it, do it in two steps with next_public_key: see Changing the key.

Keeping a signed feed fresh

A signature proves who wrote an entry, not when. A host that was taken over can keep serving an old entry that is still validly signed, so installed copies never see the newer version, or are held at an older one with a known bug. bach feed therefore signs the time it ran into every entry ("published": "2026-11-17T06:36:00Z", UTC; SOURCE_DATE_EPOCH sets it for a rebuild on purpose). An app that sets
bach.toml
ignores a signed entry that is older than that, one with no time, and one that claims to be from more than a day ahead. The time is part of the signature, so taking it off or changing it makes the entry invalid. Left out, an entry never expires, as before. The catch is yours: an entry only stays fresh when you sign it again. Run bach feed on a schedule, for example a weekly workflow that signs the current release again and uploads latest.json, or installed copies stop seeing updates after max_age_days. Feeds signed before the time existed have none, and apps with a limit refuse them.

Beta versions

An app can offer pre-release versions to the people who ask for them:
bach.toml
Build the beta (version = "2.0.0-beta.1") and write its feed to its own file: bach feed dist/Hello-Setup-2.0.0-beta.1.exe --out latest-beta.json. The stable feed stays as it is, so nobody gets a beta by accident. Each installation chooses for itself, with the installed uninstall.exe, which your app can run:
The choice lives under the user’s own HKCU\Software\Bach\Channel, survives updates and repairs, and is deleted when the app is removed. The next --check-update, --download-update or --update, and the background task, ask only the beta feed (no mirrors), with the same public_key and signer checks. An app without beta_feed answers --channel beta with exit code 1. Going back to stable never installs an older version by itself: an installed beta stays until a stable version newer than it is out.

Signed updates (Authenticode)

public_key signs the feed. signer checks the file itself:
bach.toml
The installed app runs a downloaded update only when Windows says its Authenticode signature is valid and the certificate’s common name or organisation is that text (case ignored, the whole name). It asks Windows’ own PowerShell (Get-AuthenticodeSignature) right before it installs, and again before it opens an update’s window. An unsigned file, a signature Windows does not trust or a file signed by anyone else is deleted from the download folder and not run, with the reason in the log. The online installer checks the file it downloads the same way before it installs from it. This also protects against a feed host that was taken over: it can name any file, but it cannot sign as you. A plain name matches any certificate that has it as its common name or organisation, and a certificate authority can issue that to another company of the same name. To pin the company, give the whole subject, which you can print with (Get-AuthenticodeSignature FILE).SignerCertificate.Subject: signer = "CN=Example Inc., O=Example, L=Berlin, C=DE" has to match the certificate’s subject pair for pair, so another company of the same name in another place does not. A renewed certificate keeps its subject, so the setting survives renewals. Changing the subject needs a version you hand out again, because installed copies hold the old one. bach build --sign and bach sign check the same after signing. If the signed file’s certificate is not the signer, the build stops, because every installed copy would refuse the update. Use signer together with [signing], and sign every setup file you publish, patches too. The first version with signer has to be installed by hand, because older copies do not know the setting.

Changing the key

A key has to be replaced when it leaks or is lost. Installed copies trust only what they were built with, so the new key has to reach them while the old one still works.
1

Release with both keys

Make the new key with bach feed-key and keep the old one. Build a release whose bach.toml has the old key as public_key and the new one as next_public_key, and sign its feed with the old private key. Computers that update to it now trust both keys.
2

Switch to the new key

Wait until most computers have that release. Then build the next one with public_key set to the new key (and no next_public_key), and sign its feed with the new private key. Computers on the release from step 1 accept it. Computers that never took step 1 still hold only the old key and refuse it, so they need a new download of the setup file.
If the old key leaked, whoever has it can forge the feed of step 1 until everyone has moved on. A key cannot be revoked remotely.
bach feed accepts a private key that belongs to either of the two public keys.

When a step after the files fails

Setup puts the new files in place first, then runs your [[run]] steps, shortcuts, PATH, link schemes and file types, writes the new uninstall.exe and registers the version. The old copies stay until the last of these has worked. If one fails, the files, the earlier uninstall.exe and the integration go back to the earlier version, and the version under Settings › Apps never changes. Files the new version drops are removed only after success. What a run step already did on its own, such as setting up a database, is not undone.

It survives interruptions

  • The setup window is closed: nothing was changed. The download stays, so the next try needs no network.
  • The download is cut off: it continues where it stopped and is checked against the feed’s SHA-256.
  • The app is open: the update stays ready and installs when it closes.
  • The PC is switched off, or setup crashes, in the middle: files move in together, with a journal in the install folder. The next install, update or removal, and each background round, puts back what was half moved. New files are flushed to disk before the old ones go. If a program holds a file that has to be put back, the journal stays and setup names the file to free before it tries again.
  • Something else holds a file, like a virus scanner just after the app closed: --apply-update tries up to three times, five seconds apart, and keeps the download for the next round if it still cannot.

What is checked

Downloads are https only, redirects included, through Windows’ own curl.exe. A downloaded setup file must match the feed’s SHA-256, be a setup file for the same app id and carry the version the feed says, both when it is downloaded and again right before it runs. A file in the download folder is never trusted just because it is there.
The SHA-256 comes from the same place as the file, so it guards against damage and a wrong file, not against someone who controls your release page. Sign your setup file so Windows shows your name: see Signing. Updates download the whole setup file each time. A private GitHub repository cannot serve the feed, because the app has no GitHub token to send. Use a server that checks the access key instead: see Private updates.

Mirrors

If the host of your feed is down, the app can ask another:
bach.toml
A mirror is a full feed with its own download link. Write it with bach feed "dist/Hello-Setup-1.4.0.exe" --url https://mirror.example.net/hello/Hello-Setup-1.4.0.exe --out mirror/latest.json and upload it there. The first feed that answers decides which version is newest. A mirror cannot say “there is a newer one”. It only offers another place to download the same file (same version and SHA-256), tried when the first download fails. That way a weaker mirror cannot widen what installed apps trust. When the main feed is down, the first mirror that answers is trusted like the main feed would be, so list only mirrors you run as carefully as the main one, and sign your setup files.

Staged rollouts

To ship a risky release to few people first, write the feed with a rollout:
latest.json
Each computer has a fixed number from 0 to 99, made from Windows’ machine id and the app’s id. It takes the update by itself when that number is below the rollout. Raise it with --rollout 50, then write the feed again without --rollout for everybody. A computer in the first ten percent stays in every later step.
  • Computers outside the rollout count as up to date for --check-update, --download-update and the scheduled task.
  • --update, which a person asks for, always installs.
  • The online installer ignores rollouts: new installs get the newest.
  • Apps only ever move up. To pull a bad release, publish the feed of the last good version again: apps that have not updated stay put, and apps that took the bad one wait for a higher version.

Update patches

A big app that updates often, like an Electron app with its own Chromium, can spare its users most of the download. bach build --patch-from also writes a patch: a setup file that carries only the files that changed since an earlier version.
The feed then offers it next to the full file:
latest.json

What the installed app does

  • It downloads the patch only when 1.3.0 is installed and every installed file has a checksum on record. Setup files made with this Bach version or newer have them. Every other computer downloads the full file, as before.
  • The patch is a setup file for the same app and is checked like any update: SHA-256 against the feed, same app id, the feed’s version.
  • Before it places anything, the patch checks that every file it left out is in the install folder, byte for byte (size and SHA-256). If one is not, because the user or something else changed it, nothing is touched. The app then downloads the full file and installs that. An update never ends up half done.
  • The window that --update opens (without --silent) always uses the full file, because it cannot fall back by itself. Silent updates, the background task and --download-update use patches.

Things to know

  • A patch works on whole files. A file that changed by one byte is in the patch in full, so patches pay off when most of your app’s size is files that do not change (a runtime, assets, libraries), not when it is one big program.
  • A patch is a setup file itself, so it carries the setup runtime (about 10 MB). bach build only puts a patch in the feed when it is at least a fifth smaller than the full file, and says so when it leaves it out. Force it with bach feed ... --patch.
  • Build the patch from the setup file you published for that version. You can build one patch per older version, but the feed offers one: use the version most people have.
  • After signing, write the feed again and pass the signed patch too: bach feed dist/Hello-Setup-1.4.0.exe --patch dist/Hello-Setup-1.4.0-patch-from-1.3.0.exe. The patch’s link comes from bach.toml, or from --patch-url. With --sign, bach build signs the patch as well.
  • An app with [access] gets a patch encrypted with the same key.
  • The online installer and a first install always use the full file.

Binary deltas

When bach build --patch-from finds a file that is in both versions and changed, and it is at least 64 KB, the patch stores it as what differs from the old file (zstd’s patch mode, with a window as large as both files). A 6 MB program that changed by one byte and 900 inserted bytes takes 1,075 bytes in the patch instead of 6,001,092.
  • It is exact. A delta records the SHA-256 of the file it was made from. Setup refuses it unless the installed file is exactly that one, and checks the result against the new file’s SHA-256. A program the user changed isn’t patched: nothing is touched and the app takes the full file instead.
  • A delta is used only if it is under four fifths of the file; otherwise the whole file goes in. Files over 512 MiB and files under 64 KB go in whole.
  • An earlier setup file locked with [access], or itself a patch, has no files to make deltas from.
  • The patch is still a setup file, so on disk it is the setup runtime (about 10 MB) plus its archive.

One feed for x64 and ARM64

With [arch.arm64], bach build writes an x64 and an ARM64 setup file and one latest.json that lists both. The top-level link, SHA-256 and size are the x64 file; arch.arm64 holds the ARM64 file’s own link, SHA-256, size and signature. The online installer asks Windows what the computer is; an installed app updates with the architecture it was installed with. A missing, unusable or unsigned listing falls back to the x64 file, which also runs on Windows on ARM. Older apps ignore arch and keep verifying the main entry as before.

Private updates

Without [access], the feed and the setup file must be readable by anyone. For a private app, add [access]:
bach.toml
With send_key (the default when [updates] is set), the installed app sends the key it was installed with as Authorization: Bearer <key> with every request to the feed and the download. Your server decides: answer 401 or 403 and the update is refused with “That key doesn’t fit”. The key is kept sealed for the Windows user and goes only to the host of feed, which is in the signed setup file. A feed can name any download link, so a download or a mirror on another host never gets it, and a redirect to another host, like a storage bucket’s signed link, is followed without it. Put your private download on the same host as the feed. Because the files are also encrypted with the key, the setup file is safe on a public host too. See [access] for what this does and does not protect.

Use your own server

Without GitHub, give the feed and where the file lives:
bach.toml
bach build writes latest.json next to the setup file. Upload both. The feed is a small JSON file:
latest.json
After signing, write the feed again from the signed file:
See bach feed.

Next steps

Automate in CI

Every input and output of the action.

Sign your setup file

Sign first, then the feed has the right hash.

Reference: [updates]

github, feed, download_url and auto.

Setup file command line

Every update flag.