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)