A version somebody can read, instead of a sha nobody can

Updates follow a channel now. `stable` is the newest vX.Y.Z tag; `edge` is the
branch tip, which is what this did before. Stable is the default, because a
branch tip is not a release -- following one means deploying whatever was pushed
five minutes ago, possibly mid-feature, which is right for whoever builds this
and wrong for whoever runs it. The page can now say "running 1.0.0, 1.1.0
available" rather than showing two shas and leaving somebody to guess.

Read with git plumbing and never a forge API, for three reasons in the order
they bite. It would need a token on the deployment host -- a credential that can
reach the repository, sitting on a box, to answer a read-only question about
version numbers. It would tie this to one forge, so a fork on GitHub gets
nothing. And it breaks: checked against the Gitea this is developed on, `tea
whoami` works and `tea releases list` returns a 500 from a server-side panic
about token scopes, so a page resting on that endpoint would have shipped
already broken.

Release notes still travel, inside the annotated tag object, which
`git for-each-ref` reads with no API anywhere.

Two details that are only obvious after getting them wrong. A tag with a suffix
is not a release: git's version sort puts v1.1.0-rc1 *above* v1.1.0, so
accepting one would step a stable host onto a candidate on the strength of a
hyphen. And `--sort=-v:refname` rather than a lexical sort, which puts v1.9.0
above v1.10.0 and does it silently the first time a project reaches ten of
anything -- there is a test.

What is running is `git describe --tags --always`, so it reads "1.0.0" at a tag,
"1.0.0-7-gd4f56d" seven commits past one, and a bare sha before the first
release ever exists. That last case is what `--always` is for. When it lands
exactly on a tag whose name disagrees with __version__, the page says so: a tag
cut before the version bump names a release nobody can identify afterwards, and
the check costs no subprocess because both facts are already in hand.

update.sh resolves the channel the same way and detaches at the tag rather than
resetting -- a `reset --hard <tag>` while on main would move the local branch to
it, which is a rewrite of a ref nobody asked to rewrite. A host with no tags
falls back to the branch and says so, which is every host until the release.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

deploy/README.md

@@ -45,13 +45,39 @@ Everything is overridable from the environment:
 | `HOME_DIR` | `/home/lembas` | that account's home |
 | `PREFIX` | `/srv/lembas` | install root (bind mount of `HOME_DIR`) |
 | `REPO_URL` | this checkout's `origin` | so a fork deploys itself |
-| `LEMBAS_BRANCH` | `main` | branch to deploy, and what `/admin/updates` compares against |
+| `LEMBAS_BRANCH` | `main` | branch to fetch, and what the `edge` channel follows |
+| `LEMBAS_CHANNEL` | `stable` | `stable` follows release tags, `edge` follows the branch tip |
 | `INSTALL_UPDATE_HELPER` | `0` | `1` lets the web interface deploy that branch as root |
 
+## Channels
+
+| | follows | for |
+|---|---|---|
+| `stable` (default) | the newest `vX.Y.Z` tag | anybody running this |
+| `edge` | the tip of `LEMBAS_BRANCH` | whoever is building it |
+
+**A branch tip is not a release.** Following `main` means deploying whatever was
+pushed five minutes ago, possibly mid-feature — right for development and wrong
+for a machine somebody depends on. Stable is the default for that reason.
+
+A tag with a suffix (`v1.1.0-rc1`) is deliberately **not** a release: git's
+version sort puts it *above* `v1.1.0`, so accepting one would step a stable host
+onto a release candidate on the strength of a hyphen. A prerelease is something
+you check out by name.
+
+Release notes travel inside **annotated** tags, so `git tag -a v1.1.0 -m "…"` is
+what puts them on the update page. No forge API is involved anywhere — which
+matters more than it sounds: a token on the deployment host to answer a
+read-only question about version numbers is a bad trade, it would tie this to
+one forge, and the Gitea API this was checked against returns a 500 from a
+server-side panic on exactly that endpoint.
+
 ## Updating from the web interface
 
-`/admin/updates` says what is running, what is on the branch and what changed
-between. **Checking** reaches the remote; opening the page does not.
+`/admin/updates` says what is running (`git describe`, so `1.0.0` at a tag and
+`1.0.0-7-gd4f56d` seven commits past one), what the channel offers, the release
+notes, and the commits between. **Checking** reaches the remote; opening the page
+does not.
 
 The button is opt-in, and the reason is a boundary rather than caution:
 
@@ -61,17 +87,16 @@ INSTALL_UPDATE_HELPER=1 SITE_HOST=chat.example ./deploy/install.sh
 
 That installs `lembas-update.path` and `lembas-update.service`. The web
 interface writes `$PREFIX/data/update-requested`; the path unit notices and the
-service runs `update.sh` **as root**.
+service runs `update.sh` **as root**, on the configured channel.
 
 **What that grants.** Anybody who can administer this web interface can then
 deploy whatever is on the configured branch and restart the service. That is the
 point of it, and it is why it is not the default.
 
 **What it deliberately does not grant.** The request file carries nothing that
-reaches a command line — no branch, no ref, no arguments. The branch is baked
-into the unit at install time from `LEMBAS_BRANCH`, so the button is always
-"deploy the branch this host was configured with" and never "deploy something
-else". Re-running the installer without the flag removes both units and the
+reaches a command line — no ref, no branch, no channel, no arguments. Both are
+baked into the unit at install time, so the button is always "deploy the channel
+this host was configured with" and never "deploy something else". Re-running the installer without the flag removes both units and the
 marker, and the page goes back to printing the manual command.
 
 Without the helper the page says so and shows `sudo …/deploy/update.sh`, which is

deploy/install.sh

@@ -26,6 +26,11 @@ SERVICE_USER="${SERVICE_USER:-lembas}"
 HOME_DIR="${HOME_DIR:-/home/lembas}"
 PREFIX="${PREFIX:-/srv/lembas}"
 BRANCH="${LEMBAS_BRANCH:-main}"
+# Which channel this host follows: `stable` (the newest release tag) or `edge`
+# (the branch tip). Stable by default, because a branch tip is not a release --
+# following one means deploying whatever was pushed five minutes ago, which is
+# right for whoever builds this and wrong for whoever runs it.
+CHANNEL="${LEMBAS_CHANNEL:-stable}"
 # Whether to install the units that let the web interface update this host.
 # Off, and off on a re-run that does not ask for it: it grants anybody who can
 # administer the web UI the ability to deploy the branch, as root. See the
@@ -47,7 +52,7 @@ echo "== plan =="
 echo "   host    : https://$SITE_HOST  ->  127.0.0.1:$APP_PORT"
 echo "   user    : $SERVICE_USER ($HOME_DIR)"
 echo "   prefix  : $PREFIX"
-echo "   repo    : $REPO_URL ($BRANCH)"
+echo "   repo    : $REPO_URL ($BRANCH, $CHANNEL channel)"
 if [[ "$INSTALL_UPDATE_HELPER" == "1" ]]; then
   echo "   updates : web interface may deploy $BRANCH as root (helper units)"
 else
@@ -116,6 +121,8 @@ LEMBAS_DEFAULT_THEME=moria
 # administrator could edit would turn "you may deploy the branch" into "you may
 # deploy anything".
 LEMBAS_UPDATE_BRANCH=$BRANCH
+# stable follows the newest release tag; edge follows the branch tip.
+LEMBAS_UPDATE_CHANNEL=$CHANNEL
 EOF
   sudo chown "$SERVICE_USER:$SERVICE_USER" "$ENV_FILE"
   sudo chmod 600 "$ENV_FILE"
@@ -146,13 +153,14 @@ if [[ "$INSTALL_UPDATE_HELPER" == "1" ]]; then
     sed -e "s|__PREFIX__|$PREFIX|g" \
         -e "s|__SERVICE_USER__|$SERVICE_USER|g" \
         -e "s|__UPDATE_BRANCH__|$BRANCH|g" \
+        -e "s|__UPDATE_CHANNEL__|$CHANNEL|g" \
         "$HERE/$unit" | sudo tee "/etc/systemd/system/$unit" >/dev/null
   done
   sudo systemctl daemon-reload
   sudo systemctl enable --now lembas-update.path
   sudo touch "$UPDATE_MARKER"
   sudo chown "$SERVICE_USER:$SERVICE_USER" "$UPDATE_MARKER"
-  echo "   installed. The web interface can now deploy $BRANCH and restart."
+  echo "   installed. The web interface can now deploy the $CHANNEL channel and restart."
 else
   # Removed rather than left, so turning it off is re-running without the flag
   # rather than remembering three commands. The button then says so and prints

deploy/lembas-update.service

@@ -9,9 +9,9 @@
 # why the installer says so out loud rather than doing it by default.
 #
 # **What it deliberately does not grant.** The request file carries nothing that
-# reaches this command line: no branch, no ref, no arguments. The branch is
-# baked in below, from the installer's environment, so pressing the button is
-# "deploy the branch this host was configured with" and can never be "deploy
+# reaches this command line: no ref, no branch, no channel, no arguments. Both
+# are baked in below from the installer's environment, so pressing the button is
+# "deploy the channel this host was configured with" and can never be "deploy
 # something else".
 
 [Unit]
@@ -29,6 +29,7 @@ ExecStartPre=-/usr/bin/rm -f __PREFIX__/data/update-requested
 Environment=SERVICE_USER=__SERVICE_USER__
 Environment=PREFIX=__PREFIX__
 Environment=LEMBAS_BRANCH=__UPDATE_BRANCH__
+Environment=LEMBAS_CHANNEL=__UPDATE_CHANNEL__
 ExecStart=/bin/bash __PREFIX__/app/deploy/update.sh
 # The script's own failure path prints the journal and exits non-zero, which is
 # what makes `systemctl status lembas-update` say what went wrong.

deploy/update.sh

@@ -10,6 +10,11 @@ set -euo pipefail
 SERVICE_USER="${SERVICE_USER:-lembas}"
 PREFIX="${PREFIX:-/srv/lembas}"
 BRANCH="${LEMBAS_BRANCH:-main}"
+# `stable` deploys the newest release tag; `edge` deploys the branch tip. Stable
+# is the default because a branch tip is not a release -- following one means
+# deploying whatever was pushed five minutes ago. A host with no tags yet falls
+# back to the branch and says so, rather than refusing to update at all.
+CHANNEL="${LEMBAS_CHANNEL:-stable}"
 
 APP="$PREFIX/app"
 VENV="$PREFIX/venv"
@@ -24,8 +29,38 @@ git_as() { sudo -u "$SERVICE_USER" git -C "$APP" "$@"; }
 before=$(git_as rev-parse HEAD)
 
 echo "== fetching =="
-git_as fetch --quiet origin "$BRANCH"
-git_as reset --hard --quiet "origin/$BRANCH"
+# `--tags` and `--force`: without the first, the stable channel never learns
+# about a release; without the second, a tag that was moved -- which happens to a
+# release cut wrong -- is refused rather than updated, and the host sits on the
+# old one with no sign of why.
+git_as fetch --quiet --tags --force origin "$BRANCH"
+
+# What to land on. A release tag on stable, the branch tip on edge. The tag
+# pattern deliberately excludes anything with a suffix: `v1.1.0-rc1` sorts above
+# `v1.1.0` under git's version sort, so accepting it would step a stable host
+# onto a release candidate on the strength of a hyphen.
+target="origin/$BRANCH"
+if [[ "$CHANNEL" == "stable" ]]; then
+  newest=$(git_as tag --list --sort=-v:refname \
+             | grep -E '^v?[0-9]+\.[0-9]+\.[0-9]+$' | head -1)
+  if [[ -n "$newest" ]]; then
+    target="$newest"
+  else
+    echo "   no release tags yet; following $BRANCH instead"
+  fi
+fi
+echo "   channel $CHANNEL -> $target"
+
+if [[ "$target" == "origin/$BRANCH" ]]; then
+  # Stays on the branch, which is what this always did.
+  git_as reset --hard --quiet "$target"
+else
+  # Detached at the tag. A `reset --hard <tag>` while on `main` would move the
+  # local branch to it, which is a rewrite of a ref nobody asked to rewrite --
+  # and the deployment checkout is never developed in, so being at a commit
+  # rather than on a branch is the more honest state anyway.
+  git_as -c advice.detachedHead=false checkout --force --detach --quiet "$target"
+fi
 
 after=$(git_as rev-parse HEAD)
 

src/lembas/__init__.py

@@ -1,3 +1,3 @@
 """LLeMbas - a Middle-earth themed web UI for OpenAI-compatible LLM endpoints."""
 
-__version__ = "0.9.7"
+__version__ = "0.9.8"

src/lembas/config.py

@@ -38,11 +38,20 @@ class Settings(BaseSettings):
     session_ttl: int = 60 * 60 * 24 * 30
     request_timeout: float = 300.0
 
-    # Which branch `/admin/updates` compares against and the helper deploys.
-    # Deployment configuration and deliberately not an instance setting: it
-    # decides what code runs on this machine, and a value a web administrator
-    # could edit would turn "you may deploy the branch" into "you may deploy
-    # anything". `deploy/install.sh` writes it beside the rest.
+    # What `/admin/updates` compares against and the helper deploys.
+    #
+    # Deployment configuration and deliberately not instance settings: they
+    # decide what code runs on this machine, and a value a web administrator
+    # could edit would turn "you may deploy the channel" into "you may deploy
+    # anything". `deploy/install.sh` writes both beside the rest.
+    #
+    # `stable` follows the newest release tag; `edge` follows the branch tip.
+    # Stable is the default because a branch tip is not a release -- following
+    # one means deploying whatever was pushed five minutes ago, which is right
+    # for whoever is building this and wrong for whoever is running it.
+    update_channel: Literal["stable", "edge"] = "stable"
+    # Which branch is fetched, and which one `edge` follows. Stable needs it too:
+    # a fetch has to name a branch, and tags come down with it.
     update_branch: str = "main"
 
     @model_validator(mode="after")

src/lembas/services/updates.py

@@ -1,4 +1,4 @@
-"""What is running here, what is available, and how to get from one to the other.
+"""What is running here, what is released, and how to get from one to the other.
 
 ## Why this exists
 
@@ -7,8 +7,34 @@ for everybody else: an instance somebody installed from `deploy/install.sh` and
 handed over has an administrator who can configure every part of it and cannot
 tell whether it is three releases behind.
 
-So this answers three questions — what is running, what is on the branch, and
-what changed between — and offers a button for the fourth.
+## Two channels, because a branch tip is not a release
+
+- **stable** — the newest version tag. "Running 1.0.0, 1.1.0 available."
+- **edge** — the branch tip, whatever was pushed five minutes ago.
+
+That distinction is the whole reason this is not just a commit comparison. A
+commit sha tells nobody anything, and following `main` means deploying work that
+may be half finished — the right default for whoever is building it and the wrong
+one for whoever is running it. Both channels are the same machinery asking one
+different question: *which ref am I comparing against*.
+
+## Git plumbing, never a forge API
+
+Tags are read with `git`, over the transport the checkout already has. Not the
+Gitea (or GitHub, or GitLab) API, for three reasons in the order they bite:
+
+- **It needs a token on the deployment host.** A credential that can reach the
+  repository, sitting on a box, to answer a read-only question about version
+  numbers. That is a bad trade.
+- **It is forge-specific.** A fork on GitHub, or a bare repository on a NAS,
+  would get nothing.
+- **It breaks.** Checked against the Gitea this is developed on: `tea whoami`
+  works and `tea releases list` returns a 500 from a server-side panic about
+  token scopes. An update page resting on that endpoint would have shipped
+  broken.
+
+Release notes still travel: an **annotated** tag carries its message in the tag
+object, and `git for-each-ref` reads it with no API anywhere.
 
 ## The button cannot do the work, and that is the design
 
@@ -17,21 +43,18 @@ write outside its own prefix, and it should not be able to: a web application
 that can restart its own service is one whose worst day is much worse.
 
 So the button **writes a file**, and an opt-in systemd `.path` unit watching that
-file runs `deploy/update.sh` as root. Three things follow, and all three are
-deliberate:
+file runs `deploy/update.sh` as root. Three things follow, all deliberate:
 
-- **The request file carries nothing.** No branch, no ref, no arguments. The
-  helper runs the update script with the branch *it* was configured with, so an
-  administrator of the web UI cannot choose what gets deployed — only *that* the
-  configured branch gets deployed.
+- **The request file carries nothing.** No ref, no channel, no arguments. The
+  helper runs the update script with the channel and branch *it* was configured
+  with, so an administrator of the web UI cannot choose what gets deployed —
+  only *that* the configured channel gets deployed.
 - **It is opt-in.** Without the helper the page says so and shows the command,
   which is the honest degradation and the same shape the SSH and search extras
-  already have. Installing it is a decision with a consequence worth stating:
-  anybody who can administer the web UI can then deploy whatever is on that
-  branch.
+  already have.
 - **Nothing here runs a shell.** Every subprocess is a fixed argv with
-  `shell=False`, and the only variable in any of them is the branch, which comes
-  from the environment rather than from a request.
+  `shell=False`, and the only variables in any of them are the branch and the
+  channel, which come from the environment rather than from a request.
 
 ## On "nothing executes on this machine"
 
@@ -44,6 +67,7 @@ leaving somebody to notice the tension.
 from __future__ import annotations
 
 import logging
+import re
 import subprocess
 from dataclasses import dataclass, field
 from pathlib import Path
@@ -58,6 +82,17 @@ log = logging.getLogger(__name__)
 # saying so is more use than waiting.
 GIT_TIMEOUT = 30.0
 
+CHANNEL_STABLE = "stable"
+CHANNEL_EDGE = "edge"
+CHANNELS = (CHANNEL_STABLE, CHANNEL_EDGE)
+
+# What counts as a release tag on the stable channel. `v1.2.3` or `1.2.3`, and
+# **nothing with a suffix**: `v1.1.0-rc1` sorts above `v1.1.0` under git's
+# version sort, so accepting it would step a stable instance onto a release
+# candidate on the strength of a hyphen. A prerelease is something somebody opts
+# into by name, not something a channel drifts onto.
+RELEASE_TAG = re.compile(r"^v?\d+\.\d+\.\d+$")
+
 # The file the button writes. Inside the data directory, which is the one place
 # the service account can write, and named so that finding it in a backup says
 # what it was.
@@ -68,6 +103,11 @@ REQUEST_NAME = "update-requested"
 # page render to answer a question that changes once.
 MARKER_NAME = ".update-helper"
 
+# `%H` sha, `%s` subject, `%cI` date, split on a unit separator rather than a
+# space: a commit subject contains spaces, and every other separator anybody
+# reaches for is one a subject may also contain.
+FORMAT = "--format=%H\x1f%s\x1f%cI"
+
 
 @dataclass(frozen=True)
 class Commit:
@@ -80,17 +120,44 @@ class Commit:
         return self.sha[:7]
 
 
+@dataclass(frozen=True)
+class Target:
+    """A thing this instance could be at: a release, or a branch tip."""
+
+    ref: str = ""
+    # What to call it to a person. A tag name on stable, a short sha on edge --
+    # which is why this is stored rather than derived: the two channels answer
+    # "what version is this?" with different kinds of thing.
+    label: str = ""
+    sha: str = ""
+    subject: str = ""
+    notes: str = ""
+
+    @property
+    def short(self) -> str:
+        return self.sha[:7]
+
+
 @dataclass(frozen=True)
 class State:
     """Everything the page shows, resolved in one go."""
 
     version: str = __version__
-    checkout: str = ""
+    channel: str = CHANNEL_STABLE
     branch: str = "main"
+    checkout: str = ""
+    # What is running: `git describe`, so "1.0.0" at a tag and "1.0.0-7-gd4f56d"
+    # seven commits past one. A bare sha only when there is no tag anywhere.
+    running: str = ""
     head: Commit | None = None
-    remote: Commit | None = None
+    available: Target | None = None
     behind: list[Commit] = field(default_factory=list)
     dirty: bool = False
+    # `git describe` said we are exactly at a tag whose name disagrees with
+    # `__version__`. Cheap to check -- no subprocess, both are already in hand --
+    # and it is the one thing about a release that is worth catching: a tag cut
+    # before the version bump names a release nobody can identify afterwards.
+    version_mismatch: str = ""
     helper: bool = False
     requested: bool = False
     error: str = ""
@@ -101,16 +168,24 @@ class State:
 
     @property
     def up_to_date(self) -> bool:
-        return bool(self.head and self.remote and self.head.sha == self.remote.sha)
+        return bool(self.head and self.available and self.head.sha == self.available.sha)
+
+    @property
+    def no_releases(self) -> bool:
+        """Stable, and nothing tagged yet. Worth its own answer: the page has to
+        say "nothing has been released" rather than "up to date", which would be
+        true of an empty repository and useless."""
+        return self.channel == CHANNEL_STABLE and self.available is None
 
 
 def checkout_dir() -> Path | None:
     """The git checkout this is running from, or None.
 
-    `src/lembas/__init__.py` upwards twice is the repository root for an editable
-    install, which is what every deployment here is. A wheel installed into
+    `src/lembas/services/updates.py` upwards three times is the repository root
+    for an editable install, which is what every deployment here is. A wheel in
     site-packages has no `.git` above it and answers None, which the page reads
-    as "this was not installed from a checkout" rather than as an error.
+    as "this was not installed from a checkout" rather than as an error -- and is
+    what a container correctly reports, since `.dockerignore` excludes `.git`.
     """
     root = Path(__file__).resolve().parents[3]
     return root if (root / ".git").exists() else None
@@ -144,19 +219,16 @@ def _git(args: list[str], *, cwd: Path, timeout: float = GIT_TIMEOUT) -> tuple[i
 
 
 def _commit(line: str) -> Commit | None:
-    """One line of `--format=%H\\x1f%s\\x1f%cI`.
-
-    Split on a unit separator rather than a space: a commit subject contains
-    spaces, and every other separator anybody reaches for is one a subject may
-    also contain.
-    """
     parts = line.split("\x1f")
     if len(parts) < 2 or not parts[0]:
         return None
     return Commit(sha=parts[0], subject=parts[1], when=parts[2] if len(parts) > 2 else "")
 
 
-FORMAT = "--format=%H\x1f%s\x1f%cI"
+# --- Configuration ---------------------------------------------------------------
+def channel_name() -> str:
+    wanted = (settings.update_channel or CHANNEL_STABLE).strip().lower()
+    return wanted if wanted in CHANNELS else CHANNEL_STABLE
 
 
 def branch_name() -> str:
@@ -175,6 +247,81 @@ def pending() -> bool:
     return request_path().exists()
 
 
+# --- Resolving what is available ---------------------------------------------------
+def release_tags(root: Path) -> list[str]:
+    """Every release tag, newest first.
+
+    `--sort=-v:refname` is git's own version sort, so `v1.10.0` comes above
+    `v1.9.0` -- which a lexical sort gets wrong, and gets wrong silently the
+    first time a project reaches ten of anything.
+    """
+    code, output = _git(["tag", "--list", "--sort=-v:refname"], cwd=root)
+    if code != 0:
+        return []
+    return [line.strip() for line in output.splitlines() if RELEASE_TAG.match(line.strip())]
+
+
+def _notes_for(root: Path, tag: str) -> str:
+    """An annotated tag's message: the release notes, travelling inside git.
+
+    Empty for a lightweight tag, which is the honest answer -- there is nothing
+    attached to one. `%(contents)` includes the signature block for a signed tag,
+    so it is cut at the PGP header rather than shown.
+    """
+    code, output = _git(
+        ["for-each-ref", "--format=%(contents)", f"refs/tags/{tag}"], cwd=root
+    )
+    if code != 0:
+        return ""
+    return output.split("-----BEGIN PGP SIGNATURE-----")[0].strip()
+
+
+def resolve_target(root: Path, channel: str, branch: str) -> Target | None:
+    """What this channel says the instance should be at.
+
+    Reads **local refs only**. On stable that is the tags the last fetch brought
+    down; on edge it is `origin/<branch>`, a file under `.git/refs/remotes/`.
+    Neither touches the network -- `read(fetch=True)` is what refreshes them, and
+    keeping that split is why opening the page costs nothing.
+    """
+    if channel == CHANNEL_STABLE:
+        tags = release_tags(root)
+        if not tags:
+            return None
+        tag = tags[0]
+        code, line = _git(["log", "-1", FORMAT, f"refs/tags/{tag}"], cwd=root)
+        commit = _commit(line) if code == 0 else None
+        if commit is None:
+            return None
+        return Target(
+            ref=tag,
+            label=tag.lstrip("v"),
+            sha=commit.sha,
+            subject=commit.subject,
+            notes=_notes_for(root, tag),
+        )
+
+    code, line = _git(["log", "-1", FORMAT, f"origin/{branch}"], cwd=root)
+    commit = _commit(line) if code == 0 else None
+    if commit is None:
+        return None
+    return Target(
+        ref=f"origin/{branch}", label=commit.sha[:7], sha=commit.sha, subject=commit.subject
+    )
+
+
+def _describe(root: Path) -> str:
+    """What is running, in the most human terms git can manage.
+
+    `1.0.0` exactly at a tag, `1.0.0-7-gd4f56d` seven commits past one, and a
+    bare short sha when nothing has ever been tagged. That last case is why
+    `--always` is there: without it this fails outright on a repository with no
+    tags, which is every repository before its first release.
+    """
+    code, output = _git(["describe", "--tags", "--always", "--dirty="], cwd=root)
+    return output if code == 0 else ""
+
+
 def read(*, fetch: bool = False) -> State:
     """What is running and what is available.
 
@@ -182,56 +329,73 @@ def read(*, fetch: bool = False) -> State:
     page, and a page that made a network request on every load would be one
     somebody stops opening. The Check button passes it.
     """
-    branch = branch_name()
+    channel, branch = channel_name(), branch_name()
     root = checkout_dir()
-    base = State(branch=branch, helper=helper_installed(), requested=pending())
+    base = {
+        "channel": channel,
+        "branch": branch,
+        "helper": helper_installed(),
+        "requested": pending(),
+    }
     if root is None:
-        return base
+        return State(**base)
 
     code, head_line = _git(["log", "-1", FORMAT], cwd=root)
     if code != 0:
-        return State(**{**base.__dict__, "checkout": str(root), "error": head_line})
+        return State(**base, checkout=str(root), error=head_line)
+
+    error = ""
+    if fetch:
+        # `--tags` and `--force`: without the first, stable never learns about a
+        # release; without the second, a tag that was moved (which happens to a
+        # release that was cut wrong) is refused rather than updated, and the
+        # instance sits on the old one with no sign of why.
+        code, output = _git(
+            ["fetch", "--quiet", "--tags", "--force", "origin", branch], cwd=root
+        )
+        if code != 0:
+            error = f"Could not reach the remote: {output}"
+
+    head = _commit(head_line)
+    target = resolve_target(root, channel, branch)
+    running = _describe(root)
+
+    behind: list[Commit] = []
+    if target is not None and head is not None and target.sha != head.sha:
+        code, output = _git(["log", FORMAT, f"HEAD..{target.sha}"], cwd=root)
+        if code == 0 and output:
+            behind = [c for line in output.splitlines() if (c := _commit(line))]
 
     code, status = _git(["status", "--porcelain"], cwd=root)
     dirty = bool(status.strip()) if code == 0 else False
 
-    error = ""
-    if fetch:
-        code, output = _git(["fetch", "--quiet", "origin", branch], cwd=root)
-        if code != 0:
-            error = f"Could not reach the remote: {output}"
-
-    remote_line = ""
-    code, output = _git(["log", "-1", FORMAT, f"origin/{branch}"], cwd=root)
-    if code == 0:
-        remote_line = output
-
-    behind: list[Commit] = []
-    if remote_line:
-        code, output = _git(["log", FORMAT, f"HEAD..origin/{branch}"], cwd=root)
-        if code == 0 and output:
-            behind = [c for line in output.splitlines() if (c := _commit(line))]
+    # Exactly at a tag whose name disagrees with the version this process
+    # reports. No subprocess: `running` and `__version__` are both already here.
+    mismatch = ""
+    if RELEASE_TAG.match(running) and running.lstrip("v") != __version__:
+        mismatch = running.lstrip("v")
 
     return State(
+        **base,
         checkout=str(root),
-        branch=branch,
-        head=_commit(head_line),
-        remote=_commit(remote_line) if remote_line else None,
+        running=running,
+        head=head,
+        available=target,
         behind=behind,
         dirty=dirty,
-        helper=helper_installed(),
-        requested=pending(),
+        version_mismatch=mismatch,
         error=error,
     )
 
 
+# --- Asking for it -----------------------------------------------------------------
 def request_update(who: str = "") -> str:
     """Ask the helper to update. Returns a message fit to show.
 
     The file is written with the requester's email in it **for the log**, and
     that is all it carries. Nothing in it reaches the helper's command line: the
-    helper runs the update script with its own configured branch, so being able
-    to press this button is not being able to choose what is deployed.
+    helper runs the update script with its own configured channel and branch, so
+    being able to press this button is not being able to choose what is deployed.
     """
     path = request_path()
     try:
@@ -256,18 +420,26 @@ def manual_command() -> str:
 
 
 __all__ = [
+    "CHANNELS",
+    "CHANNEL_EDGE",
+    "CHANNEL_STABLE",
     "GIT_TIMEOUT",
     "MARKER_NAME",
+    "RELEASE_TAG",
     "REQUEST_NAME",
     "Commit",
     "State",
+    "Target",
     "branch_name",
+    "channel_name",
     "checkout_dir",
     "clear_request",
     "helper_installed",
     "manual_command",
     "pending",
     "read",
+    "release_tags",
     "request_path",
     "request_update",
+    "resolve_target",
 ]

src/lembas/web/templates/admin/updates.html

@@ -7,8 +7,12 @@
 
 {% block admin_content %}
 <p class="admin-lede">
-  What is running here, what is on <code>{{ state.branch }}</code>, and what
-  changed between. Checking reaches the remote; opening this page does not.
+  This host follows the
+  <strong>{{ "stable" if state.channel == "stable" else "edge" }}</strong>
+  channel{% if state.channel == "stable" %} — the newest release tag{% else %} —
+  the tip of <code>{{ state.branch }}</code>, which is whatever was pushed most
+  recently and may be half finished{% endif %}.
+  Checking reaches the remote; opening this page does not.
 </p>
 
 {% if saved %}
@@ -23,16 +27,25 @@
   <dl class="mode-list">
     <div class="mode-list__row">
       <dt><strong>Version</strong></dt>
-      <dd>{{ state.version }}</dd>
+      <dd>
+        {#
+          `git describe`, not the version string: "1.0.0" exactly at a tag and
+          "1.0.0-7-gd4f56d" seven commits past one. The second is the honest
+          answer for an edge instance, where the version string alone would claim
+          to be a release it is not.
+        #}
+        <strong>{{ state.running or state.version }}</strong>
+        {% if state.running and state.running != state.version %}
+        <span class="faint text-xs">(reports {{ state.version }})</span>
+        {% endif %}
+      </dd>
     </div>
     {% if state.head %}
     <div class="mode-list__row">
       <dt><strong>Commit</strong></dt>
       <dd>
         <code>{{ state.head.short }}</code> {{ state.head.subject }}
-        {% if state.dirty %}
-        <span class="badge">uncommitted changes</span>
-        {% endif %}
+        {% if state.dirty %}<span class="badge">uncommitted changes</span>{% endif %}
       </dd>
     </div>
     {% endif %}
@@ -44,10 +57,21 @@
     {% endif %}
   </dl>
 
+  {% if state.version_mismatch %}
+  <div class="alert alert--warning">
+    {{ icon("warning", "icon--sm") }}
+    <span>
+      This is tagged <strong>{{ state.version_mismatch }}</strong> but reports
+      version <strong>{{ state.version }}</strong>. A tag cut before the version
+      bump names a release nobody can identify afterwards.
+    </span>
+  </div>
+  {% endif %}
+
   {% if not state.is_git %}
   <p class="field__hint">
     This was not installed from a git checkout — a container image, or a wheel —
-    so there is nothing here to compare or update. Update the image instead.
+    so there is nothing here to compare or update. Pull a new image instead.
   </p>
   {% else %}
   <form method="post" action="/admin/updates/check" class="btn-row">
@@ -62,30 +86,54 @@
 <section class="card">
   <h2 class="card__title">
     Available
-    {% if state.up_to_date %}<span class="badge badge--leaf">up to date</span>
-    {% elif state.behind %}<span class="badge">{{ state.behind | length }} behind</span>
+    {% if state.no_releases %}<span class="badge">nothing released yet</span>
+    {% elif state.up_to_date %}<span class="badge badge--leaf">up to date</span>
+    {% elif state.behind %}<span class="badge">{{ state.behind | length }} commit{{ '' if state.behind|length == 1 else 's' }} behind</span>
     {% endif %}
   </h2>
 
-  {% if not state.remote %}
+  {% if state.no_releases %}
   <p class="field__hint">
-    Nothing known about <code>origin/{{ state.branch }}</code> yet. Check the
-    remote above.
+    Nothing on <code>{{ state.branch }}</code> has been tagged as a release yet,
+    so the stable channel has nothing to offer. Switch this host to
+    <code>edge</code> in <code>lembas.env</code> to follow the branch instead.
   </p>
+
+  {% elif not state.available %}
+  <p class="field__hint">
+    Nothing known about the remote yet. Check it above.
+  </p>
+
   {% elif state.up_to_date %}
   <p class="field__hint">
-    <code>{{ state.remote.short }}</code> is what is running.
+    <strong>{{ state.available.label }}</strong> is what is running.
   </p>
+
   {% else %}
   <p class="card__lede">
-    <code>{{ state.remote.short }}</code> {{ state.remote.subject }}
+    <strong>{{ state.available.label }}</strong>
+    <span class="faint">— {{ state.available.subject }}</span>
   </p>
 
   {#
-    The log between, not just a count. "3 behind" is a number somebody has to go
-    and look up; the subjects are the thing that decides whether this is worth
+    Release notes, out of the annotated tag itself. Escaped and preformatted,
+    never through services/markdown.py: this comes from a tag object rather than
+    from a template, and markdown is the one path allowed to emit HTML.
+  #}
+  {% if state.available.notes %}
+  <pre class="tool-result__text">{{ state.available.notes }}</pre>
+  {% endif %}
+
+  {#
+    The commits between, not just a count. "3 behind" is a number somebody has to
+    go and look up; the subjects are what decides whether this is worth
     restarting for right now.
   #}
+  {% if state.behind %}
+  <details>
+    <summary class="text-sm">
+      {{ state.behind | length }} commit{{ '' if state.behind|length == 1 else 's' }} between
+    </summary>
     <ul class="model-list">
       {% for commit in state.behind %}
       <li class="model-list__item">
@@ -95,18 +143,19 @@
       </li>
       {% endfor %}
     </ul>
+  </details>
+  {% endif %}
 
   {% if state.dirty %}
   <div class="alert alert--warning">
     {{ icon("warning", "icon--sm") }}
     <span>
-      This checkout has uncommitted changes. The update does a hard reset, which
-      would throw them away — nothing here is meant to be edited in place, so
-      this usually means somebody was debugging on the box.
+      This checkout has uncommitted changes, and updating discards them.
+      Nothing here is meant to be edited in place, so this usually means somebody
+      was debugging on the box.
     </span>
   </div>
   {% endif %}
-
   {% endif %}
 </section>
 
@@ -134,15 +183,18 @@
   {% elif state.helper %}
   <p class="card__lede">
     This host has the update helper installed, so the button below writes a
-    request that a systemd unit picks up and runs as root. It always deploys
-    <code>{{ state.branch }}</code> — the request carries no branch and no ref,
-    so pressing it is never “deploy something else”.
+    request that a systemd unit picks up and runs as root. It always deploys the
+    <strong>{{ state.channel }}</strong> channel — the request carries no ref and
+    no channel, so pressing it is never “deploy something else”.
   </p>
   <form method="post" action="/admin/updates/apply" class="btn-row"
         data-confirm="Update and restart? Replies being written are saved; open terminals are cut off.">
-    <button class="btn btn--primary" type="submit" {{ 'disabled' if state.up_to_date }}>
+    <button class="btn btn--primary" type="submit"
+            {{ 'disabled' if state.up_to_date or state.no_releases }}>
       {{ icon("sparkle", "icon--sm") }}
-      {{ "Nothing to apply" if state.up_to_date else "Update and restart" }}
+      {% if state.no_releases %}Nothing released
+      {% elif state.up_to_date %}Nothing to apply
+      {% else %}Update to {{ state.available.label }} and restart{% endif %}
     </button>
   </form>
   <p class="field__hint">
@@ -164,12 +216,11 @@
   <p class="field__hint">
     To install it, re-run the installer with
     <code>INSTALL_UPDATE_HELPER=1</code>. Doing so means anybody who can
-    administer this web interface can deploy whatever is on
-    <code>{{ state.branch }}</code> — which is the point, and worth deciding on
-    purpose rather than arriving at.
+    administer this web interface can deploy the <code>{{ state.channel }}</code>
+    channel — which is the point, and worth deciding on purpose rather than
+    arriving at.
   </p>
   {% endif %}
 </section>
 {% endif %}
 {% endblock %}
-

tests/test_updates.py

@@ -14,6 +14,29 @@ from lembas.config import settings
 from lembas.services import updates
 
 
+@pytest.fixture
+def tagged():
+    """A release tag on HEAD, with notes in the annotated tag object.
+
+    Made and removed around the test rather than assumed: this repository has no
+    tags until the release, and a test that needed one to exist would pass once
+    and then start failing for the wrong reason.
+    """
+    import subprocess
+
+    root = updates.checkout_dir()
+    subprocess.run(
+        ["git", "tag", "-a", "v9.9.9", "-m", "Ninth release.\n\n- one thing"],
+        cwd=root, check=True, capture_output=True,
+    )
+    try:
+        yield "v9.9.9"
+    finally:
+        subprocess.run(
+            ["git", "tag", "-d", "v9.9.9"], cwd=root, check=False, capture_output=True
+        )
+
+
 @pytest.fixture(autouse=True)
 def clean():
     updates.clear_request()
@@ -71,6 +94,10 @@ def test_the_running_commit_is_reported(db):
     assert state.version
     assert state.head is not None
     assert len(state.head.short) == 7
+    # `git describe`, so a tagged checkout says "1.0.0" and an untagged one says
+    # a short sha rather than failing outright -- which is what `--always` is
+    # there for, and is every repository before its first release.
+    assert state.running
 
 
 def test_a_commit_subject_with_separators_survives():
@@ -93,6 +120,79 @@ def test_a_git_that_is_not_there_is_a_message_and_not_a_crash(db, monkeypatch, t
     assert "git" in state.error
 
 
+# --- Channels ---------------------------------------------------------------------
+def test_only_a_release_shaped_tag_counts_as_one(db):
+    """`v1.1.0-rc1` sorts *above* `v1.1.0` under git's version sort, so accepting
+    a suffix would step a stable instance onto a release candidate on the
+    strength of a hyphen."""
+    for good in ("v1.0.0", "1.0.0", "v10.2.30"):
+        assert updates.RELEASE_TAG.match(good), good
+    for bad in ("v1.1.0-rc1", "v1.0", "nightly", "v1.0.0+build", "release-1"):
+        assert not updates.RELEASE_TAG.match(bad), bad
+
+
+def test_stable_picks_the_newest_release_and_reads_its_notes(db, tagged):
+    """Notes travel inside the annotated tag object, so there is no forge API
+    anywhere in this -- which matters, because the API this was checked against
+    returns a 500 from a server-side panic."""
+    root = updates.checkout_dir()
+
+    assert updates.release_tags(root)[0] == "v9.9.9"
+    target = updates.resolve_target(root, updates.CHANNEL_STABLE, "main")
+
+    assert target.label == "9.9.9"
+    assert "one thing" in target.notes
+
+
+def test_a_version_sort_is_not_a_lexical_one(db, tagged):
+    """`v1.10.0` above `v1.9.0`, which a lexical sort gets wrong -- and gets
+    wrong silently the first time a project reaches ten of anything."""
+    import subprocess
+
+    root = updates.checkout_dir()
+    for tag in ("v1.9.0", "v1.10.0"):
+        subprocess.run(["git", "tag", tag], cwd=root, check=True, capture_output=True)
+    try:
+        tags = updates.release_tags(root)
+        assert tags.index("v1.10.0") < tags.index("v1.9.0")
+    finally:
+        subprocess.run(
+            ["git", "tag", "-d", "v1.9.0", "v1.10.0"], cwd=root, check=False,
+            capture_output=True,
+        )
+
+
+def test_edge_follows_the_branch_tip(db):
+    root = updates.checkout_dir()
+    target = updates.resolve_target(root, updates.CHANNEL_EDGE, updates.branch_name())
+
+    # A short sha rather than a version: the two channels answer "what version
+    # is this?" with different kinds of thing, which is why the label is stored
+    # rather than derived.
+    assert target is None or len(target.label) == 7
+
+
+def test_stable_with_nothing_tagged_says_so(db, monkeypatch):
+    """"Nothing has been released" is not "up to date" -- the second would be
+    true of an empty repository and useless."""
+    monkeypatch.setattr(updates, "release_tags", lambda root: [])
+    monkeypatch.setattr(updates, "channel_name", lambda: updates.CHANNEL_STABLE)
+
+    state = updates.read()
+
+    assert state.no_releases is True
+    assert state.up_to_date is False
+
+
+def test_a_tag_that_disagrees_with_the_version_is_flagged(db, tagged):
+    """A tag cut before the version bump names a release nobody can identify
+    afterwards. Costs no subprocess: both facts are already in hand."""
+    state = updates.read()
+
+    assert state.version_mismatch == "9.9.9"
+    assert state.version != "9.9.9"
+
+
 # --- The request ------------------------------------------------------------------
 def test_the_request_file_carries_nothing_that_reaches_a_command(db):
     """No branch, no ref, no arguments. Being able to press the button is
@@ -114,11 +214,20 @@ def test_a_request_can_be_withdrawn(db):
     assert updates.pending() is False
 
 
-def test_the_branch_comes_from_the_environment_and_not_a_request(db):
-    """Deployment configuration rather than an instance setting: it decides what
+def test_the_channel_and_branch_come_from_the_environment(db):
+    """Deployment configuration rather than instance settings: they decide what
     code runs here, and a value a web administrator could edit would turn "you
-    may deploy the branch" into "you may deploy anything"."""
+    may deploy the channel" into "you may deploy anything"."""
     assert updates.branch_name() == settings.update_branch
+    assert updates.channel_name() in updates.CHANNELS
+
+
+def test_an_unknown_channel_falls_back_to_stable(db, monkeypatch):
+    """A value stored by an older version, or a typo in lembas.env. Falling back
+    to edge would silently start deploying unreleased work."""
+    monkeypatch.setattr(settings, "update_channel", "nightly")
+
+    assert updates.channel_name() == updates.CHANNEL_STABLE
 
 
 # --- The page ---------------------------------------------------------------------
@@ -203,6 +312,7 @@ def test_the_helper_units_take_no_branch_from_the_request():
     unit = (root / "deploy/lembas-update.service").read_text()
 
     assert "__UPDATE_BRANCH__" in unit
+    assert "__UPDATE_CHANNEL__" in unit
     assert "update-requested" in unit  # deleted, not read
     assert "ExecStart=/bin/bash __PREFIX__/app/deploy/update.sh" in unit
     # Deleted before the script runs, or the path unit re-arms on a file that is