# Releasing GarageStack --- ## Deployment Options GarageStack ships two ways. Users pick one. | Option | Best for | Images used | |--------|----------|-------------| | **All-in-one** | Unraid, NAS, single-machine homelab | `garagestack` | | **Separate services** | Docker Compose on a server, more control | `garagestack-frontend`, `garagestack-api`, `garagestack-worker` + external postgres + mosquitto | --- ## Published Images All images live on GitHub Container Registry (`ghcr.io`). Replace `joszz` with the actual username. | Image | Purpose | |-------|---------| | `ghcr.io/joszz/garagestack` | All-in-one (Unraid / single container) | | `ghcr.io/joszz/garagestack-frontend` | nginx serving the Vue SPA | | `ghcr.io/joszz/garagestack-api` | ASP.NET Core REST API | | `ghcr.io/joszz/garagestack-worker` | .NET background worker (MQTT + push) | ### Tags Produced Per Image | Tag | Example | When created | |-----|---------|--------------| | `latest` | `garagestack:latest` | The newest release: its `vX.Y.Z` tag, then the weekly rebuild of that release (Mondays 05:00 UTC) and a manual release rebuild. Never a push to `main`, and never an older patch release or a pre-release | | `edge` | `garagestack:edge` | Every push to `main` and a manual rebuild of `main`. Unreleased changes, migrations included, as soon as they are merged | | `1.2.3` | `garagestack:1.2.3` | On `v1.2.3` git tag, and again with each weekly rebuild while it is the newest release | | `1.2` | `garagestack:1.2` | On any `v1.2.x` tag | | `1` | `garagestack:1` | On any `v1.x.x` tag | | `sha-abc1234` | `garagestack:sha-abc1234` | Every published build, named after the commit it was built from: pushes to `main`, tags, weekly rebuild, manual dispatch | | `pr-123` | `garagestack:pr-123` | Preview of pull request 123 while it has the `test-build` label; follows every push (a fork's is rebuilt by hand), deleted when the label comes off or the PR closes. See [`PREVIEW_BUILDS.md`](PREVIEW_BUILDS.md) | | `pr-123-abc1234` | `garagestack:pr-123-abc1234` | One exact commit of that preview; deleted with it | --- ## Pipeline ### Overview ``` PR opened CI (project rules, lint, typecheck, test, build, e2e, container-build for amd64 and arm64, infra-lint) CodeQL (actions, C#, JS/TS analysis) Security (Trivy filesystem scan) docker-publish (only when the PR changes docker-publish.yml itself; pushes nothing) PR labelled test-build (see PREVIEW_BUILDS.md) Preview build (calls docker-publish: push pr- and pr--, no signing/SBOM) Comment on the PR with the image names and commands for the tester Repeats on every push while the label is on PR closed or test-build label removed Preview cleanup (delete the pr- image versions) Merge to main CI (without container-build: docker-publish builds the images) CodeQL Security (Trivy filesystem + image scan after publish) Dependency submission (graph snapshot to GitHub) docker-publish (build amd64 on ubuntu-latest and arm64 on ubuntu-24.04-arm, push each by digest, then one merge job per image tags the multi-architecture index with short SHA + edge) Attach SBOM + provenance (one per architecture, kept in the index) Sign the index and each manifest in it with Cosign Release tag pushed (vX.Y.Z) docker-publish (same, tagging the index X.Y.Z, X.Y, X, short SHA and, for the newest release, latest) Attach SBOM + provenance Sign the index and each manifest in it with Cosign Weekly (Mondays) CodeQL Security (Trivy filesystem + image scan) docker-publish (rebuild the newest release from its tag with today's OS packages and re-push X.Y.Z, X.Y, X and latest) ``` --- ## Release Process A release is cut by hand: tag a commit on `main`, then publish a GitHub release with notes written for the people upgrading. Pushing the tag is what publishes the versioned images; nothing else has to happen for the release to reach users. ### Before tagging - **CI is green on the commit you release.** `gh run list --branch main --limit 5` shows the latest runs. - **Pick the version.** A release that carries upgrade notes, new configuration options or database migrations is a minor bump (`0.x.0`), even when every commit in it is a fix or a refactor. A patch (`0.x.y`) is for fix-only releases that drop in without anyone doing anything. `1.0.0` is for the first public release. ### Tag and publish Tag the commit by its SHA, so nothing has to be checked out and uncommitted work in your tree does not matter: ```bash git fetch origin git tag -a v1.2.3 -m "v1.2.3" git push origin v1.2.3 gh release create v1.2.3 --verify-tag --latest --notes-file release-notes.md ``` Watch the image builds at `https://github.com/joszz/garagestack/actions`. The tag build publishes `X.Y.Z`, `X.Y`, `X` **and** `latest`. This is the only moment users on `latest` (the Unraid template among them) get the changes merged since the last release, so a fix users notice is worth a patch release of its own. A push to `main` publishes `edge` only and never touches `latest`, whatever order the runs finish in. To rebuild the newest release by hand (for an OS package fix before Monday), run **Build and publish Docker images** from `main` with target `release`. It checks the newest `vX.Y.Z` tag out and re-pushes `X.Y.Z`, `X.Y`, `X` and `latest` from it. ### Release notes Notes are written by hand from the descriptions of the pull requests merged since the last release. Group them under these headings, leaving out the ones that are empty, and end each line with its PR number in parentheses: 1. **Upgrade Notes** - only when something has to be done or changes behaviour on upgrade 2. **Features** 3. **Bug Fixes** 4. **Security** 5. **Performance** 6. **Documentation** 7. **Internal** 8. **Dependencies** 9. **Full Changelog** - the compare link between the two tags `gh release view ` shows the last release's notes to copy the format from. ### Commit Convention Commits to `main` follow [Conventional Commits](https://www.conventionalcommits.org/). They set no version (you pick it), but the type is what places a change under a heading in the release notes: ``` (): ``` | Type | Release notes heading | Example | |------|-----------------------|---------| | `feat` | Features | `feat: add trip heatmap export` | | `fix` | Bug Fixes | `fix: correct kWh calculation` | | `perf` | Performance | `perf: load the map card without the vector basemap` | | `docs` | Documentation | `docs: add a configuration reference` | | `refactor`, `test`, `ci`, `build`, `chore` | Internal | `refactor: split MapView into its parts` | | `feat!` or a `BREAKING CHANGE` footer | Also under Upgrade Notes | `feat!: rename API routes` | --- ## CI and Quality Gates The `ci` workflow runs on every PR and push to `main`. All jobs must pass before a PR can be merged. | Job | What it checks | |-----|---------------| | `project-rules` | Rules from `CLAUDE.md` no linter knows: no em dash anywhere in the repository | | `frontend-lint` | oxlint, ESLint and Stylelint (no fixable issues left uncommitted), Prettier format | | `frontend-typecheck` | `vue-tsc --build` (zero type errors) | | `frontend-test` | Vitest unit tests | | `e2e` | The production bundle behind the production nginx config (the only place the Content-Security-Policy applies), driven by the Playwright smoke tests against the demo stack | | `backend-build` | `dotnet build --configuration Release` with warnings as errors, `dotnet format --verify-no-changes`, and a check that the EF model has no change without a migration | | `backend-test` | `dotnet test` (all xUnit tests) | | `container-build` | Docker build (no push) for all four images, each for amd64 and for arm64 on its own runner. The amd64 jobs keep the names the ruleset requires; the arm64 jobs are named `Container build (, arm64)`. Pull requests only: on `main`, `docker-publish` builds and pushes them | | `infra-lint` | shellcheck on every `*.sh`, hadolint on every Dockerfile (deliberate exceptions in `.hadolint.yaml` and inline `# hadolint ignore` comments), actionlint on the workflows | ### Code Analysis (CodeQL) The `codeql` workflow runs alongside CI on every PR, every push to `main`, and weekly on Mondays at 07:00 UTC. It analyzes three language targets: `actions` (workflow files), `csharp` (backend), and `javascript-typescript` (frontend). Results appear in the GitHub Security tab. --- ## Dependency Management [Dependabot](https://docs.github.com/en/code-security/dependabot) opens weekly PRs on Mondays for outdated packages across npm (frontend), NuGet (backend), the Dockerfiles' base images, the image tags in `docker-compose.yml` (Mosquitto, PostgreSQL, the SAIC gateway) and GitHub Actions. Actions are pinned to commit SHAs with the version in a trailing comment; Dependabot updates both. ### Auto-merge Rules The `auto-merge` workflow merges Dependabot PRs automatically when CI passes, covering: - **All patch updates** (any package, any ecosystem, including GitHub Actions) - **Minor updates** for any named Dependabot group (the condition is `dependency-group != ''`) -- this covers GitHub Actions too, via the `docker-actions`/`github-actions` groups below Named groups defined in `.github/dependabot.yml`: | Ecosystem | Groups | | --------- | ------ | | npm | `vue-ecosystem`, `vite-and-pwa`, `map-and-charts`, `fontawesome`, `linting`, `typescript-and-types`, `testing` | | NuGet | `dotnet-platform`, `identity-model`, `serilog`, `test-framework` | | GitHub Actions | `docker-actions`, `github-actions` | Everything else (ungrouped minor and all major updates) requires manual review and merge. --- ## Security Scanning The `security` workflow runs Trivy on every PR, every push to `main`, and weekly on Mondays at 07:00 UTC. ### Filesystem Scan Scans source code and dependency manifests for known CVEs: - Reports `CRITICAL` and `HIGH` severity findings as SARIF, visible under the GitHub Security tab - **Fails the build** on any unfixed `CRITICAL` vulnerability ### Image Scan After images are pushed to GHCR, each `:latest` image is scanned separately, once per architecture (`linux/amd64` and `linux/arm64`, picked out of the index with `TRIVY_PLATFORM`). Results appear in the Security tab under per-image categories: `trivy-image-` for amd64 and `trivy-image--arm64` for arm64. --- ## Supply Chain Security ### SBOM Every published image includes a Software Bill of Materials generated by BuildKit and attached as an OCI attestation alongside the manifest. The image is built per architecture, so the SBOM and the provenance below are listed per platform (`linux/amd64`, `linux/arm64`). Inspect the SBOM: ```bash docker buildx imagetools inspect ghcr.io/joszz/garagestack:latest \ --format '{{ json .SBOM }}' ``` ### Provenance Attestation Each image includes a full SLSA provenance attestation (`mode=max`) recording the exact build inputs, environment, and steps. Inspect provenance: ```bash docker buildx imagetools inspect ghcr.io/joszz/garagestack:latest \ --format '{{ json .Provenance }}' ``` ### Cosign Image Signing Every released image is signed with [Cosign](https://docs.sigstore.dev/cosign/overview/) using keyless signing via GitHub Actions OIDC. No long-lived signing keys are stored anywhere. The multi-architecture index is signed, which covers every tag, and so is each manifest inside it (`cosign sign --recursive`), so verifying one architecture's own digest works too. Verify a signature (the workflow signs with Cosign 3, so use Cosign 3 or newer to verify): ```bash cosign verify \ --certificate-identity-regexp "^https://github.com/joszz/GarageStack/" \ --certificate-oidc-issuer "https://token.actions.githubusercontent.com" \ ghcr.io/joszz/garagestack:latest ``` A successful verification confirms the image was built by this repository's workflow and was not tampered with after publishing. ### Dependency Submission The `dependency-submission` workflow runs on every push to `main`. It uses the `component-detection-dependency-submission-action` to snapshot all dependency graphs (npm, NuGet, GitHub Actions) and submit them to GitHub. This powers the Dependency graph and Dependabot alerts in the repository Security tab. --- ## Stale Issues and PRs The `stale` workflow runs every Monday at 08:00 UTC: - Issues and PRs inactive for **60 days** are labelled `stale` - Issues and PRs still inactive after a further **14 days** are closed - Exempt labels for issues: `pinned`, `security`, `bug`, `enhancement` - Exempt labels for PRs: `pinned`, `security`, `do-not-merge` - Issues and PRs attached to a milestone are always exempt --- ## Versioning (MinVer) GarageStack uses MinVer for .NET assembly version metadata and for the version shown in the UI footer. - Source of truth is git history + tags with `v` prefix (e.g. `v1.2.3`) - On non-tag commits, MinVer produces prerelease versions using `preview.0` as the identifier (e.g. `0.5.1-preview.0.12`, so `edge` images built from `main` show that instead of the last release) - If no `v*` tags exist yet, MinVer starts from `0.0.0-preview.0.` - In CI, the workflow computes MinVer once and passes it to all Docker builds as `APP_VERSION` - The frontend Dockerfiles forward `APP_VERSION` to Vite as `VITE_APP_VERSION`; `pnpm dev` hides the version - `docker-compose.build.yml` (the source build on top of `docker-compose.yml`) passes `APP_VERSION` through from the shell or `.env` and defaults to `0.0.0-local`. Source builds cannot read git history inside Docker, so build with `APP_VERSION=$(git describe --tags)` in front of the command to show the real version. A leading `v` is stripped, since MinVer rejects it **Do not manually set `` in `*.csproj` or `package.json` for releases.** MinVer reads it from git. Use `0.x.y` while in active development, `1.0.0` for the first public release. --- ## Required Secrets and Permissions | Secret / Permission | Where | Purpose | |--------------------|-------|---------| | `GITHUB_TOKEN` | Auto-provided | GHCR login, Dependabot auto-merge | | `GHCR_PAT` | Optional repo secret | Override GITHUB_TOKEN for GHCR push | | `DOCKERHUB_USERNAME` | Repo secret | Avoid Docker Hub pull rate limits during builds | | `DOCKERHUB_TOKEN` | Repo secret | Avoid Docker Hub pull rate limits during builds | | Actions: Read and write permissions | Repo settings | Required for GHCR push and release creation | | `id-token: write` | Merge job of `docker-publish.yml` (and the `preview-build.yml` job that calls it, since a called workflow cannot ask for more than its caller grants) | Cosign keyless signing via OIDC | | Allow auto-merge | Repo settings > General | `auto-merge` queues Dependabot PRs with `gh pr merge --auto` | | Allow GitHub Actions to create and approve pull requests | Repo settings > Actions > General | `auto-merge` approves Dependabot PRs so branch protection's review rule is met | --- ## Making GHCR Packages Public After the very first successful workflow run, each package is created as private. Repeat once per image (four times total): 1. GitHub profile -> **Packages** 2. Select the package 3. **Package settings** -> **Change visibility** -> **Public** ### Never delete untagged versions Each image is a multi-architecture index: only the index carries tags, and the per-architecture images and attestations it points to show up as untagged versions on the package page. A cleanup that deletes untagged versions (such as `actions/delete-package-versions` with `delete-only-untagged-versions`) deletes those too, and every tag that points at them then fails to pull. Public packages cost nothing to store, so untagged versions are left alone. Previews are the exception: `preview-cleanup.yml` deletes them by their `pr-` tag, which works because previews are single-architecture. --- ## Published Images with Docker Compose `docker-compose.yml` runs the published `garagestack-api`, `garagestack-worker` and `garagestack-frontend` images at `${GARAGESTACK_TAG:-latest}`, so a Compose install picks up a release with `docker compose pull` and nothing in the file changes when a release is cut. `docker-compose.build.yml` builds the same three services from the clone instead (see [Building from source](CONFIGURATION.md#building-from-source)); a preview is just `GARAGESTACK_TAG=pr-`. A version tag (`1.2.3`) gives exactly that release. `latest` is the newest release, rebuilt weekly with the base images' security fixes but never with unreleased code. `edge` follows `main`, so it carries unreleased changes, migrations included, as soon as they are merged. Going back from `edge` to `latest` is not supported once a newer migration has run: stay on `edge` until the next release catches up. --- ## Unraid Community Apps The Unraid template lives at [unraid/garagestack.xml](../unraid/garagestack.xml). It tracks the `:latest` tag, which only gets new code when a release is tagged, so Unraid users receive releases automatically and never unreleased work from `main`. No template change is needed when cutting a new release. ### One-time submission to Community Apps The CA system requires a **separate dedicated repository** based on the [unraid-community-apps-starter](https://github.com/unraid/unraid-community-apps-starter) template. The main GarageStack repo is not read directly. **Steps:** 1. Ensure the GitHub repo is **public** and the MIT `LICENSE` file is committed 2. Ensure all four GHCR packages are **public** (see [Making GHCR Packages Public](#making-ghcr-packages-public)) 3. Go to [github.com/unraid/unraid-community-apps-starter](https://github.com/unraid/unraid-community-apps-starter) and click **Use this template** to create a new repo (e.g. `joszz/unraid-community-apps`) 4. In the new repo, fill in `ca_profile.xml` (description, icon, project link, support link) 5. Copy `unraid/garagestack.xml` from this repo into `templates/garagestack.xml` in the new repo 6. Update the `` inside that copy to point to its new raw URL: `https://raw.githubusercontent.com/joszz/unraid-community-apps/main/templates/garagestack.xml` 7. Go to [ca.unraid.net/submit/new](https://ca.unraid.net/submit/new) and submit the new repo URL 8. Once approved, GarageStack appears in the Community Apps search ### Manual install (before CA approval or for testing) Unraid users can install directly without waiting for CA approval: > Unraid UI -> Apps -> Install from URL -> `https://raw.githubusercontent.com/joszz/garagestack/main/unraid/garagestack.xml` ### Keeping the Community Apps copy in sync The template uses `:latest`, so a release on its own needs no template change. `unraid/garagestack.xml` changes when a variable, port, volume, name or description changes, and **every such change has to be copied to the Community Apps repository as well**. Community Apps installs only from [`joszz/unraid-community-apps`](https://github.com/joszz/unraid-community-apps), so a change made here alone never reaches the users who installed from there. The comment at the top of the template says the same, for whoever edits it next. The two copies differ only in ``: each one points at itself. Copy the whole file across on a branch, restore that one line, and open a pull request there, just as for a change here: ```bash cd unraid-community-apps git switch main && git pull git switch -c sync/ curl -fsSL https://raw.githubusercontent.com/joszz/garagestack/main/unraid/garagestack.xml \ | sed 's#raw.githubusercontent.com/joszz/garagestack/main/unraid/garagestack.xml#raw.githubusercontent.com/joszz/unraid-community-apps/main/templates/garagestack.xml#' \ > templates/garagestack.xml git diff # only the template's own changes, never the TemplateURL git commit -am "Sync garagestack.xml with joszz/garagestack ()" git push -u origin sync/ gh pr create --repo joszz/unraid-community-apps --base main --fill ``` Do this once the template change is on `main` here, so both copies describe the same image. Community Apps reads the template from that repository's `main`, so the sync reaches users only once its pull request is merged. When the app's description changes, update `ca_profile.xml` and `README.md` in that repository too. --- ## Rollback If a release is broken, tag the last good commit with a new patch version: ```bash git tag v1.2.4 git push origin v1.2.4 ``` Find the previous release SHA: ```bash git log --oneline --tags ``` --- ## Troubleshooting GHCR Denied Errors If workflow logs show `denied: denied` during push, common causes: 1. **Workflow permissions** not set to **Read and write** in Repository Settings -> Actions -> General. 2. Package-level access does not allow this repository to publish to the GHCR package. 3. Org policy blocks the default workflow token -- create a `GHCR_PAT` secret with `read:packages` and `write:packages` scopes. The workflow runs a GHCR auth preflight per image before the expensive build steps and fails early with a clear permission message.