> ## 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.

# Build setup files in CI with the GitHub Action

> Build a Bach setup file on any CI runner with the usebach/bach GitHub Action or the install scripts, with inputs, outputs and Windows, macOS and Linux notes.

`bach build` exits with a non-zero code and a readable message on any problem, so it fits in a pipeline as it is, on Windows, macOS or Linux. The GitHub Action installs `bach`, builds the setup file, and can sign it and publish it as a release your installed apps update from.

> [!TIP]
>
> Don't want to write the workflow? `bach init` or `bach workflow` adds a complete one-click release to your repository: see [One-click releases](/docs/guides/releasing.md).

## The GitHub Action

Build and publish a release for every pushed tag like `v1.4.0`:

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

The tag is the app's version, so there is no second place to keep it. Set `[updates] github = "owner/repo"` in `bach.toml` and installed apps update from these releases: see [Updates](/docs/guides/updates.md).

Or only build, and publish the file yourself:

```yaml .github/workflows/build.yml theme={"theme":{"light":"github-light","dark":"github-dark"}}
- uses: usebach/bach@v0
  id: bach
  with:
    config: bach.toml
- uses: actions/upload-artifact@v4
  with:
    path: ${{ steps.bach.outputs.setup }}
```

| Input | Default | Meaning |
| - | - | - |
| `config` | none | A `bach.toml` to build. Leave empty to only install `bach`. |
| `version` | the version you pinned | The Bach version to build with: `0.2.1` exactly, `0.2` or `0` for the newest of that line, `latest`, or `local` for a `bach` already on the `PATH`. By default it follows the tag in `uses: usebach/bach@v0.2`, the Cargo.toml version for a commit SHA, and the latest release for a branch. |
| `args` | none | More arguments for `bach build`, like `--fast` or `--patch-from OLD.exe`, written like a command line: spaces separate words and quotes keep a value with spaces in one piece (`--patch-from "dist/My App 1.0.exe"`). Nothing is expanded, backslashes stay as they are, and a word cannot contain a line break. |
| `app-version` | `auto` | The app's version. `auto` takes it from the tag the run is for (`v1.4.0` gives `1.4.0`) and keeps `bach.toml`'s on other runs. A version sets it, an empty string keeps `bach.toml`'s. |
| `sign-command` | none | A PowerShell command that signs `$env:BACH_SETUP_FILE`. It runs before the feed is written, and runs again for the online installer when there is one. Windows runners only. |
| `notes`, `notes-file` | none | What is new, stored in the update feed and used as the release notes |
| `release` | `false` | `true` publishes the setup file, the online installer (when `bach.toml` builds one) and `latest.json` as a GitHub release, creating the tag if needed |
| `tag` | `v` plus the version | The release's tag |
| `compare` | `false` | `true` runs `bach diff` against the file of the latest release: files added, removed and changed, and how much bigger or smaller the setup file got. The report goes to the job summary and, on a pull request, into one comment that later pushes update (the job needs `pull-requests: write`; a pull request from a fork gets only the summary). The earlier file is found by name: `Hello-Setup-1.4.0.exe` is looked for as `Hello-Setup-*.exe`. Nothing is compared when there is no earlier release or it has no such file. |
| `prerelease` | `false` | A pre-release is not GitHub's "latest", so installed apps do not update to it |
| `draft` | `false` | Save the release as a draft |
| `latest` | `true` | `false` keeps this release from becoming "latest" (a fix to an older line) |
| `github-token` | the workflow's token | Publishes the release and looks Bach's releases up |

| Output | Meaning |
| - | - |
| `setup` | The path of the setup file `bach build` wrote |
| `web-setup`, `patch` | The path of the [online installer](/docs/reference/config/installer.md#online-and-offline-installers), when `bach.toml` builds one |
| `version` | The version the setup file carries |
| `feed` | The path of `latest.json`, when `bach.toml` has `[updates]` |
| `tag`, `release-url` | The release, when `release` is `true` |
| `bach-version` | The Bach version that was installed |

For an app with [`[access]`](/docs/reference/config/access), store the key as a repository secret and pass it to the action's step as the environment variable the build reads, `BACH_ACCESS_KEY` by default:

```yaml .github/workflows/release.yml theme={"theme":{"light":"github-light","dark":"github-dark"}}
- uses: usebach/bach@v0
  env:
    BACH_ACCESS_KEY: ${{ secrets.BACH_ACCESS_KEY }}
  with:
    config: bach.toml
```

The action runs `bach doctor` on the config first, then `bach build`. It works on Windows, macOS and Linux runners.

### Pin the action

`usebach/bach@v0` follows the newest 0.x release, `@v0.2` 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`. A Bach release moves `v0` and `v0.2` only after all its downloads are on the release.

> [!NOTE]
>
> Outside Windows the setup file keeps Bach's icon. Build on `windows-latest` to apply `app.icon`.

## Without the action

Install `bach` with the scripts, then build:

> [tab] Windows runner
>
> ```powershell theme={"theme":{"light":"github-light","dark":"github-dark"}}
> irm https://raw.githubusercontent.com/usebach/bach/main/install.ps1 | iex
> bach build
> ```
>
> Set `BACH_NO_PATH` to skip changing the user's `PATH` on a CI machine.

> [tab] macOS or Linux runner
>
> ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
> curl -fsSL https://raw.githubusercontent.com/usebach/bach/main/install.sh | sh
> bach build
> ```
>
> `bach` downloads `bach-setup.exe` itself the first time it builds, and checks its SHA-256.

Pick a version with `BACH_VERSION`: `0.2.0` for exactly that one, `0.2` or `0` for the newest of that line, `latest` for the newest. See [Environment variables](/docs/reference/setup/environment-variables.md).

## A typical release pipeline

1. Build your app into the folder named by `files.source`.
2. Run the Bach action with `release: true`, and `sign-command` to sign on a Windows runner (see [Signing](/docs/guides/signing.md)). It writes the update feed after signing.
3. Without the action: run `bach build`, sign with `signtool`, run `bach feed` on the signed file, and upload the setup file and `latest.json`.

## Offline or locked-down runners

If the runner cannot download the runtime, keep `bach-setup.exe` next to `bach`, pass `--runtime PATH`, or set `BACH_RUNTIME`. Set `BACH_NO_DOWNLOAD` to make `bach` refuse to download anything.


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