# Preview builds A preview build is a set of throwaway images for one pull request, so someone with the right car can try a fix before it is merged. It exists because most of GarageStack's drivetrain code (BEV and PHEV charging, battery counters) cannot be checked on the maintainer's own car: the person who reported the problem is the only one who can say whether the fix works. - Add the **`test-build`** label to a pull request and every image is published as **`pr-`**. - Every push to the pull request replaces those images. - Removing the label, closing the pull request or merging it **deletes the images again**. - `latest`, `edge`, the version tags and the `sha-` tags are never touched, so nobody else notices. - A pull request **from a fork** is built by hand instead, after you have read it: see [Pull requests from forks](#pull-requests-from-forks). Contents: - [Maintainer checklist](#maintainer-checklist), with [Pull requests from forks](#pull-requests-from-forks) - [Testing a preview build](#testing-a-preview-build) (the part to send testers to), with [My data is gone after switching](#my-data-is-gone-after-switching) - [Database changes](#database-changes) - [How it works](#how-it-works) - [Troubleshooting](#troubleshooting) - [Before a build: ask for data](#before-a-build-ask-for-data) --- ## Maintainer checklist 1. **Branch and pull request as usual.** Create the branch with `--no-track` from `origin/main` and open a pull request to `main`. While the fix is unproven, refer to the issue with `Refs #123` rather than `Fixes #123`, so a merge does not close the issue before the tester has confirmed it. 2. **Keep migrations out if you can.** See [Database changes](#database-changes). 3. **Add the `test-build` label.** The *Preview build* workflow publishes the four images (a few minutes, since it reuses the build cache of `main`) and then posts a comment on the pull request with the exact image names and commands. That comment is updated on every later push. 4. **Point the tester at it.** Comment on the issue, for example: > A build with a possible fix is ready to try. If you're not on the latest release yet, update to it first. Then switch your GarageStack image to `pr-123` as described in [this comment](link to the preview comment), use the car as usual for a day, and let me know what the dashboard shows. Afterwards switch back to the latest release. Step by step: [Testing a preview build](https://github.com/joszz/GarageStack/blob/main/documentation/PREVIEW_BUILDS.md#testing-a-preview-build). 5. **Iterate.** Push more commits to the same branch. The `pr-123` tag follows the pull request, so the tester only has to pull again (Unraid: *Force update*; Compose: `docker compose pull` and `docker compose up -d` again). The version in the footer (on a phone, at the bottom of the menu) ends in `.pr.123`, and the comment shows which commit it is. 6. **Finish.** - **It works:** merge. The images are deleted, the fix is on `edge` right away and reaches everyone on `latest` with the next release. Ask the tester to switch to `edge` until that release is out (or cut a patch release), then back to `latest`. Straight back to `latest` before the release is only safe when the preview had no database warning. - **It does not work:** close the pull request (or just remove the label while you rethink). The images are deleted and nothing else changed. Need a fresh build without a new commit, for example to pick up a newer `main`? Remove the label and add it again. ### Pull requests from forks A pull request from a fork never gets permission to publish packages, so the label alone builds nothing there: the *Preview build* run shows as skipped. Building it means running the contributor's code with this repository's permission to publish, so it only happens when you start it, for a commit you have read. 1. **Read the changes**, Dockerfiles and build files included. The workflows always run as they are on `main`, so changes the pull request makes to `.github/workflows/` take no part in the build. 2. **Add the `test-build` label.** The build refuses a pull request without it, so that closing the pull request or removing the label deletes the images, as for any other preview. 3. **Run the workflow** with the pull request number and the commit you read, its head: ```sh gh pr view 123 --json headRefOid --jq .headRefOid gh workflow run preview-build.yml -f pr_number=123 -f commit= ``` Or in the Actions tab: *Preview build*, *Run workflow*. It checks that the pull request is still at that commit, then builds GitHub's merge of it into `main`, as for a branch of this repository. If the contributor has pushed since you read it, the run stops and names the new head. 4. **After every push from the contributor**, read the new commits and run it again with the new head. The images do not follow the pull request by themselves, and the preview comment says so to the tester. A build by hand reads the build cache of `main` but writes none: whatever a fork's build produced would otherwise be cached under `main`, where the releases are built from. --- ## Testing a preview build *This section is written for testers. Link to it from issues.* A preview build is GarageStack with one change in it that has not been released yet. It runs on your own data like a normal update, and you can go back to the normal version at any time. **Before you start:** - **Run the latest release first.** On an older version, update to the latest release as usual (its release notes say whether anything needs doing), check that it runs, and only then switch to the preview. The preview is built on top of that release, the database warning in the preview comment compares with it, and going back means going back to it. Skipping it means the preview also applies the database changes of every release in between, and going back to your old version is then not supported. - **Switch where you always run GarageStack:** the same folder, Portainer stack or Unraid container, changing only the image. Docker Compose names the database volume after the folder or stack (`mg_postgres_data` for a folder called `mg`), so the same stack started from another folder, a fresh clone for example, runs on a new, empty database. Your old data is then still there, just not in use (see [My data is gone after switching](#my-data-is-gone-after-switching)). - **Never run** `docker compose down -v`, `docker volume prune` or `docker system prune --volumes` while testing. Those do delete data. - **Back up the database** when the preview comment warns that the build changes the database (see [Backup and restore](../README.md#backup-and-restore)). Without the warning a backup is not required, but it takes one command and never hurts. Replace `pr-123` below with the tag from the pull request comment. ### All-in-one container or Unraid Change the image from `ghcr.io/joszz/garagestack:latest` to: ```text ghcr.io/joszz/garagestack:pr-123 ``` - **Unraid:** edit the container, change *Repository*, apply. - **docker run:** stop and remove the container, then run it again with the new image and the same volumes and variables. - **Compose with the all-in-one image:** change the `image:` line, then `docker compose pull && docker compose up -d`. When the maintainer says a new version is ready, pull the same tag again (Unraid: *Force update*). ### Docker Compose **With this repository's `docker-compose.yml`:** add the preview tag to your `.env` file: ```sh GARAGESTACK_TAG=pr-123 ``` **With your own compose file** that runs `ghcr.io/joszz/garagestack-api`, `garagestack-worker` and `garagestack-frontend`: change the tag of those three images to `pr-123`. Leave everything else (database, broker, gateway, volumes) as it is, and in the folder you always run it from: ```sh docker compose pull docker compose up -d ``` For a newer version of the same preview, run both commands again. If you build from source with `docker-compose.build.yml`, take it out of `COMPOSE_FILE` while testing: a build ignores the tag. ### Checking that it runs The version in the footer ends in `.pr.123` (for example `v0.13.2-preview.0.4.pr.123`). ### Going back Change the tag back to `latest` or to the release you had, for example `0.14.0` (with this repository's compose file: remove the `GARAGESTACK_TAG` line from `.env`), then pull and start again as above. `latest` only gets new code when a release is published, so both give you a released version without the preview's changes. Your data stays. Readings collected while the preview ran stay too. ### What to report On the issue: what you did, what GarageStack showed, and what the MG app showed for the same moment. Screenshots help. **Remove your VIN, location and other personal details first.** Preview images are deleted when the pull request is closed or merged. If your container then fails to update, that is why: switch back as described above. ### My data is gone after switching The preview almost certainly did not delete it. GarageStack is running on another, empty database, and the old one is still on your disk. **Don't prune or remove volumes** until it is back. 1. List the volumes and stacks: ```sh docker volume ls docker compose ls ``` 2. **Two database volumes** (for example `mg_postgres_data` and `garagestack_postgres_data`): the preview ran under another project name. Stop the stack you run now with `docker compose down` (no `-v`), go to the folder you used before and start it there as you always do. Or keep the current folder and point it at the old volume at the bottom of its compose file: ```yaml volumes: postgres_data: external: true name: mg_postgres_data ``` 3. **All-in-one image without a `/data` volume** in your compose file or `docker run` command: Docker kept the data in an unnamed volume, and the new container got a fresh one. `docker volume ls -f dangling=true` lists the volumes no container uses; the old database is one of them. Mount it at `/data` (as `external: true` in compose, or `-v :/data`), and keep it mounted from then on. Readings the car sent while the empty database was in use stay in that one; everything from before is in the old one. Not sure which volume is which? Post the output of step 1 on the issue. --- ## Database changes A tester runs the preview against their real database. If the build carries an EF Core migration, it is applied on start, and switching back does **not** undo it. The build is the pull request merged into the current `main`, so a migration merged into `main` after the latest release reaches the tester too, even when the pull request itself has none. The warning compares with the latest release because testers are asked to run it before they switch; one who skips that also gets the migrations of the releases in between. Usually the older version still runs on the newer schema, but not always (for example a new non-nullable column without a default). - Prefer fixes without a migration in a preview. Display, mapping and calculation fixes rarely need one. - When a migration is unavoidable, the preview comment carries a warning automatically (it compares `src/GarageStack.Data/Migrations/` in the build with the latest release, so a migration only on `main` counts too). Say it in your issue comment too. GarageStack has no built-in backups, so the tester makes their own. - If the fix is dropped, a migration left in a tester's database stays there. Make the eventual real migration tolerate that (for example `IF NOT EXISTS` in raw SQL), or ask the tester to restore their backup. --- ## How it works | Piece | What it does | | ----- | ------------ | | [`preview-build.yml`](../.github/workflows/preview-build.yml) | Runs on `labeled`, `synchronize` and `reopened` for pull requests to `main`. When the pull request has the `test-build` label and comes from this repository, it calls `docker-publish.yml` with the pull request number, then posts or updates the preview comment (found by the hidden marker ``). For a fork's pull request it runs by hand (`workflow_dispatch` with the number and the reviewed commit): a check job first confirms the pull request is open, labelled and still at that commit. | | [`docker-publish.yml`](../.github/workflows/docker-publish.yml) | The normal image pipeline, callable through `workflow_call` with `pr_number`. For a preview it pushes `pr-` and `pr--`, and stamps the version with `.pr.`. It skips the SBOM, provenance and Cosign signature, so each image is a single registry version that the cleanup can find by tag. | | [`preview-cleanup.yml`](../.github/workflows/preview-cleanup.yml) | Runs when a labelled pull request closes or loses the label, or by hand (*Run workflow* with a pull request number). It listens on `pull_request_target`, so a fork's pull request can delete its images too; it never checks out the pull request's code. Deletes every version of the four packages tagged `pr-` or `pr--`, and rewrites the preview comment to say so. | | [`docker-compose.yml`](../docker-compose.yml) | Runs `ghcr.io/joszz/garagestack-*:${GARAGESTACK_TAG}`, `latest` by default, so a tester who runs from a clone only sets `GARAGESTACK_TAG=pr-` in `.env`. | Details worth knowing: - **Which commit is built.** Like CI, the build uses GitHub's merge of the pull request into the current `main`, so the tester also gets everything merged since the branch was made. The `pr--` tag names the pull request's own commit. A fork's build by hand builds that merge only while it is the merge of the commit given, and otherwise stops. - **Images per build.** All four: the all-in-one image and the three Compose services. A new push replaces `pr-`; the older build keeps its `pr--` tag until the cleanup removes it. Only rebuilding the very same commit (label off and on) leaves the previous build untagged, which costs a little registry space and nothing else. - **Concurrency.** The build and the cleanup share the group `preview-`: closing a pull request stops a build that is still pushing before the images are deleted. A newer push cancels the build of the previous one. - **Who can trigger it.** Only people who can label pull requests (triage access and up), and only for branches in this repository. A fork's pull request never gets the packages permission: only someone with write access can build it, by hand, for a commit they name (see [Pull requests from forks](#pull-requests-from-forks)). - **Update check.** A preview's version is a pre-release of the next patch, so the footer does not offer the current release as an update. - **Trivy and the security workflow** do not scan previews; they scan `latest` after each publish as before. --- ## Troubleshooting **The label does nothing.** Check that the pull request targets `main`, comes from a branch in this repository, and that the label is spelled `test-build`. A pull request from a fork is never built by the label: see [Pull requests from forks](#pull-requests-from-forks). If the label does not exist yet: ```sh gh label create test-build --color 5319E7 --description "Publish pr- preview images for testers" ``` **The cleanup fails with 403 or "not found".** The workflow token may delete a package version only when the repository has the *Admin* role on that package. For each of `garagestack`, `garagestack-frontend`, `garagestack-api` and `garagestack-worker`: open the package on GitHub, *Package settings*, *Manage Actions access*, and set this repository to *Admin*. Then run *Preview cleanup* by hand with the pull request number. **Images are left behind** (for example after a failed cleanup). Run *Preview cleanup* from the Actions tab with the pull request number. To see what is there (a local `gh` login needs the `read:packages` scope for this: `gh auth refresh -s read:packages`): ```sh gh api --paginate "users/joszz/packages/container/garagestack/versions" \ --jq '.[] | select(any(.metadata.container.tags[]; startswith("pr-"))) | {id, tags: .metadata.container.tags}' ``` **The tester's update fails after the pull request closed.** The images are gone by design. They switch back to the latest release, to `edge` once the fix is merged, or to `latest` once it is released. **A tester runs the all-in-one image on ARM.** Releases are built for amd64 and arm64, but a preview is amd64 only: the cleanup deletes package versions by tag, and the per-architecture images of a multi-architecture image carry none. An ARM tester runs the preview under emulation, with `platform: linux/amd64` on the service, which is slower. Docker Desktop on a Mac has the emulation built in; on an ARM Linux host (a Raspberry Pi, say) it has to be installed first, for example with `docker run --privileged --rm tonistiigi/binfmt --install amd64`, or the container fails with `exec format error`. --- ## Before a build: ask for data A preview build answers "does the fix work on your car". Often the first question is "what does your car actually send", and that needs no build at all: - Ask the reporter for the zip from **Settings > Data & API > Diagnostics > Download diagnostics**. It holds the last 7 days of telemetry per car (`cars/car-1/telemetry.csv`) without the VIN or the position columns, the detected car type and configuration codes, and the week's warnings from the logs, so it can be attached to the issue as is. - For an older day, ask for the relevant columns of `vehicles/{vin}/telemetry.csv` from **Settings > Data & API > Your data > Download everything**, for that day, **without the VIN and the latitude/longitude columns**. - Turn those rows into unit test fixtures and fix against the real numbers. - Then publish a preview so the reporter can confirm it on the car.