> ## Documentation Index
> Fetch the complete documentation index at: /docs/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Bach builds Windows installers from one bach.toml with the bach command: bach init, bach check, bach preview, bach build. Installs are per user and need no administrator rights by default. installer.scope = "machine" installs for every user after one Windows prompt. On Windows, run setup files with Start-Process -Wait -PassThru in PowerShell, and give signtool arguments that start with the word sign.

# Ship updates: from GitHub releases to self-updating apps

> Publish updates from GitHub with the Bach action, and let installed apps download them in the background and install them when the app closes, even after a power cut.

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.

> [!WARNING]
>
> 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:

```json latest.json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "version": "1.4.0",
  "url": "https://github.com/owner/repo/releases/download/v1.4.0/Hello-Setup-1.4.0.exe",
  "sha256": "<sha-256 of the setup file>",
  "notes": "Faster start",
  "size": 10187776
}
```

**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](/docs/reference/config/installer.md#online-and-offline-installers) uses the same feed, so publishing a release updates installed apps and what new users get.

## Where to host updates

| You have | Set | Notes |
| - | - | - |
| A public GitHub repository | `github = "owner/repo"` | The release workflow does everything. The repository must be public. |
| Static hosting: Cloudflare R2 or Pages, S3, Netlify, your own web server | `feed` and `download_url` | Upload the setup file and `latest.json` to fixed addresses. Nothing else to run. |
| Two places, for safety | `mirrors = [...]` | More feeds, asked when the main one is down. See [Mirrors](#mirrors). |
| A private server | [`[access]`](/docs/reference/config/access) | The server checks `Authorization: Bearer <key>`. See [Private updates](#private-updates). |

## Publish updates from GitHub

> [!TIP]
>
> 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](/docs/guides/releasing.md). The steps below are the same thing written by hand.

**1. Point bach.toml at your repository**

```toml bach.toml theme={"theme":{"light":"github-light","dark":"github-dark"}}
[updates]
github = "owner/repo"
```

`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**

```yaml .github/workflows/release.yml theme={"theme":{"light":"github-light","dark":"github-dark"}}
on:
  push:
    tags: ['v*']
permissions:
  contents: write
jobs:
  release:
    runs-on: windows-latest
    steps:
      - uses: actions/checkout@v4
      # ... build your app into the folder [files] source names ...
      - uses: usebach/bach@v0
        with:
          config: bach.toml
          release: true
```

**3. Push a tag**

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
git tag v1.4.0
git push origin v1.4.0
```

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:

| | Link |
| - | - |
| Feed | `https://github.com/owner/repo/releases/latest/download/latest.json` |
| Setup file | `https://github.com/owner/repo/releases/download/v1.4.0/<file>` |

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](/docs/guides/ci.md).

### 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]`](/docs/reference/config/updates)).

## What your app can do

The installed `uninstall.exe` answers these commands, with or without the scheduled task:

| Command | Result |
| - | - |
| `--check-update` | Exit code `10` when a newer version is out, `0` when up to date (or when a [staged rollout](#staged-rollouts) has not reached this computer) |
| `--check-update --json` | One line of JSON: `app`, `current`, `latest`, `available`, `downloaded`, `notes`, `size` |
| `--download-update` | Downloads it in the background and keeps it ready. Exit code `10`: ready. |
| `--apply-update` | Installs what was kept ready. `--wait-for PID` lets your app end first, `--launch` starts it again after. |
| `--update` | Downloads it (or uses the one kept ready) and opens its setup window. `--silent` installs without a window. |

To update when the user quits:

**1. At start, in the background**

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
$p = Start-Process "$env:LOCALAPPDATA\Programs\Hello\uninstall.exe" -ArgumentList '--download-update' -Wait -PassThru   # PowerShell; $p.ExitCode is 10 when an update is ready
```

**2. When the user quits, or picks restart to update**

Start this and exit:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
Start-Process "$env:LOCALAPPDATA\Programs\Hello\uninstall.exe" -ArgumentList '--apply-update', '--wait-for', '<your process id>', '--launch'   # PowerShell
```

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`:

```toml bach.toml theme={"theme":{"light":"github-light","dark":"github-dark"}}
[updates]
public_key = "3f9a…64 hex digits…"
```

`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](#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

```toml bach.toml theme={"theme":{"light":"github-light","dark":"github-dark"}}
[updates]
public_key = "3f9a…64 hex digits…"
max_age_days = 90
```

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:

```toml bach.toml theme={"theme":{"light":"github-light","dark":"github-dark"}}
[updates]
feed = "https://example.com/hello/latest.json"            # stable
beta_feed = "https://example.com/hello/latest-beta.json"  # beta
```

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:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
uninstall.exe --channel beta      # follow the beta feed from now on
uninstall.exe --channel stable    # back to the stable feed
uninstall.exe --channel show      # say which one this is
```

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:

```toml bach.toml theme={"theme":{"light":"github-light","dark":"github-dark"}}
[updates]
signer = "Example Inc."     # as the signing certificate shows it
```

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]`](/docs/reference/config/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.

> [!WARNING]
>
> 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.

> [!NOTE]
>
> 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](/docs/guides/signing.md). 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](#private-updates).

## Mirrors

If the host of your feed is down, the app can ask another:

```toml bach.toml theme={"theme":{"light":"github-light","dark":"github-dark"}}
[updates]
feed = "https://example.com/hello/latest.json"
download_url = "https://example.com/hello/{file}"
mirrors = ["https://mirror.example.net/hello/latest.json"]
```

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:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
bach feed "dist/Hello-Setup-1.4.0.exe" --rollout 10
```

```json latest.json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{ "version": "1.4.0", "url": "…", "sha256": "…", "rollout": 10 }
```

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.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
bach build --patch-from "old/Hello-Setup-1.3.0.exe"
```

```console theme={"theme":{"light":"github-light","dark":"github-dark"}}
Wrote dist\Hello-Setup-1.4.0.exe (37.8 MB)
Wrote dist\Hello-Setup-1.4.0-patch-from-1.3.0.exe (17.7 MB), the update patch from 1.3.0: 1 of 4 files changed
  Update feed  dist\latest.json
```

The feed then offers it next to the full file:

```json latest.json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "version": "1.4.0", "url": "…/Hello-Setup-1.4.0.exe", "sha256": "…",
  "delta": { "from": "1.3.0", "url": "…/Hello-Setup-1.4.0-patch-from-1.3.0.exe", "sha256": "…" }
}
```

### 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]`](/docs/reference/config/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]`](/docs/reference/config/arch), `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]`](/docs/reference/config/access), the feed and the setup file must be readable by anyone. For a private app, add `[access]`:

```toml bach.toml theme={"theme":{"light":"github-light","dark":"github-dark"}}
[access]                  # encrypts the files with a key and asks for it at install
get_key_url = "https://example.com/buy"

[updates]
feed = "https://downloads.example.com/hello/latest.json"
download_url = "https://downloads.example.com/hello/{file}"
```

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]`](/docs/reference/config/access) for what this does and does not protect.

## Use your own server

Without GitHub, give the feed and where the file lives:

```toml bach.toml theme={"theme":{"light":"github-light","dark":"github-dark"}}
[updates]
feed = "https://example.com/hello/latest.json"
download_url = "https://example.com/hello/{file}"   # {file}: the setup file's name
```

`bach build` writes `latest.json` next to the setup file. Upload both. The feed is a small JSON file:

```json latest.json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "version": "1.4.0",
  "url": "https://example.com/hello/Hello-Setup-1.4.0.exe",
  "sha256": "<sha-256 of the setup file>",
  "notes": "A line about what's new",
  "size": 10187776
}
```

After signing, write the feed again from the signed file:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
bach feed "dist/Hello-Setup-1.4.0.exe" --notes "Faster start"
```

See [`bach feed`](/docs/reference/cli/feed).

## Next steps

> [card] [Automate in CI](/docs/guides/ci.md)
>
> Every input and output of the action.

> [card] [Sign your setup file](/docs/guides/signing.md)
>
> Sign first, then the feed has the right hash.

> [card] [Reference: \[updates\]](/docs/reference/config/updates)
>
> github, feed, download\_url and auto.

> [card] [Setup file command line](/docs/reference/setup/command-line.md)
>
> Every update flag.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.