From b5ab1fe69bac0d4d8fd6263362b763ac9e22ceb9 Mon Sep 17 00:00:00 2001
From: Alexandre Moore <alexandre.j.moore@gmail.com>
Date: Sat, 18 Jul 2026 16:02:49 +0200
Subject: [PATCH] Split image publishing into stable and nightly channels

- Release tags (vX.Y.Z) publish X.Y.Z / X.Y / X and own the latest tag
  (metadata-action flavor latest=auto); master pushes no longer touch
  latest
- Master builds publish as nightly (+ master branch tag and commit sha),
  fully automatic, no git tag involved
- Daily scheduled rebuild so nightly picks up base-image security
  updates without a code change
- README documents the tag channels and how to cut a release
---
 .github/workflows/docker-publish.yml | 16 ++++++++++++++--
 README.md                            | 12 ++++++++++++
 2 files changed, 26 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/docker-publish.yml b/.github/workflows/docker-publish.yml
index ecf3302..b1fea5d 100644
--- a/.github/workflows/docker-publish.yml
+++ b/.github/workflows/docker-publish.yml
@@ -4,6 +4,10 @@ on:
   push:
     branches: [master]
     tags: ['v*.*.*']
+  # Nightly rebuild of master: picks up base-image (security) updates even
+  # when no code changed. Publishes the same nightly tag.
+  schedule:
+    - cron: '0 4 * * *'
 
 env:
   REGISTRY: ghcr.io
@@ -41,13 +45,21 @@ jobs:
         uses: docker/metadata-action@v5
         with:
           images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
+          # Tagging scheme:
+          #   release tag vX.Y.Z -> X.Y.Z, X.Y, X and latest (stable channel)
+          #   master push        -> nightly, master and the commit sha
+          # `latest` therefore always points at the last tagged release,
+          # never at an arbitrary master build (flavor latest=auto only
+          # applies it on semver tag events).
+          flavor: |
+            latest=auto
           tags: |
-            type=ref,event=branch
             type=semver,pattern={{version}}
             type=semver,pattern={{major}}.{{minor}}
             type=semver,pattern={{major}}
+            type=raw,value=nightly,enable={{is_default_branch}}
+            type=ref,event=branch
             type=sha,prefix=
-            type=raw,value=latest,enable={{is_default_branch}}
 
       - name: Build and push Docker image
         uses: docker/build-push-action@v6
diff --git a/README.md b/README.md
index 4ab262a..d741e87 100644
--- a/README.md
+++ b/README.md
@@ -37,6 +37,18 @@ docker run -d \
 # Access the web interface at http://localhost:8080
 ```
 
+#### Image tags
+
+| Tag | Meaning |
+|-----|---------|
+| `latest` | Last tagged release (stable channel) |
+| `X.Y.Z`, `X.Y`, `X` | Specific release versions |
+| `nightly` | Latest master build, also rebuilt daily for base-image updates |
+| `<sha>` | Exact commit builds |
+
+Releases are cut by pushing a git tag: `git tag v2.0.0 && git push origin v2.0.0`.
+Images are only published after the full test suite passes.
+
 Or with Docker Compose:
 
 ```bash