fix(deploy): take the version from the image being deployed, not from git HEAD

Observed in production: `teploy deploy --image .../fylun-web:462d7a7` printed
"Deployed fylun-web version fe82bf0", named the containers
`fylun-web-web-fe82bf0`, and wrote fe82bf0 into `teploy log` — while running the
image tagged 462d7a7. fe82bf0 was simply the local git HEAD at that moment.

During a rollback that is worse than cosmetic. `teploy log` is where an operator
picks a target, and every version in it named a commit that had no relationship
to the image that ran.

Cause, in deployAppConfig: gitShortHash() was called FIRST and unconditionally,
with the image consulted only in its *error* branch. So inside any git repo the
version was always HEAD and the image tag was never read. And because step 3
resolves `image = appCfg.Image` beforehand, a teploy.yml pinning a prebuilt
image hit the same path with no flag passed — this was never about --image.

versionFromImage derives the label from the reference. A digest wins over an
accompanying tag, because Docker resolves the digest and ignores the tag, so
labelling `repo:1.2.3@sha256:...` as 1.2.3 would be the same class of lie. The
tag is read only when the last colon falls after the last slash, or a registry
port (100.108.123.49:49152/tyler/app) parses as a tag.

Output is gated on Docker's tag grammar, not merely parsed. Versions are
interpolated UNQUOTED into remote shell commands through ContainerName, and
until now a version could only originate from git output or an operator's own
--version; an image reference is a less-trusted source and is treated as one.

":latest" and untagged references are refused, falling back to the existing
timestamp. Reusing a floating tag as the version gives every deploy the same
container name and leaves CurrentHash == PreviousHash, which disables rollback
outright. A timestamp is at least unique. This is a behaviour change for
build-with-pinned-yml-image deploys, documented in the CHANGELOG.

plan.go carried a comment promising it resolved the version "exactly as deploy
does" and no longer did; left alone it would predict container names the deploy
never creates. Now shares the same rule.

LogEntry gains `image`, so the log can be checked against what ran instead of
being taken on faith. AppState already carried ImageRef and ImageDigest; the
log was the gap.

Checked the four places a version string travels: container naming (needs the
grammar gate above), Caddy routing (name-only, unaffected), rollback target
resolution (matches the teploy.version label — opaque strings are fine, but a
NON-UNIQUE version would break it, which is why :latest is refused), and
keep_versions pruning (groups by the same label, unaffected).

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CfMxUBzUH4UP3reJ71j59K

Author: im-tyler

CHANGELOG.md

@@ -4,6 +4,36 @@ All notable changes to teploy are documented here. Format follows [Keep a Change
 
 ## [Unreleased]
 
+### Fixed
+
+- `deploy` labelled the deploy with the local git HEAD even when deploying a
+  prebuilt image, so the container name, `teploy log` and the operator's screen
+  all named a commit whose code was not running. Observed as "Deployed version
+  fe82bf0" while running the image tagged `462d7a7`. The version now comes from
+  the image when one is given; `--version` still wins over everything.
+
+  This was never specific to the `--image` flag — a `teploy.yml` pinning a
+  prebuilt image hit the identical problem with no flag passed.
+
+  **Behaviour change:** with an image that carries no usable version (untagged,
+  or `:latest`), `deploy` now labels with a timestamp rather than the git hash.
+  A git hash there asserts a commit that may not be what `:latest` resolves to;
+  a timestamp asserts nothing except uniqueness, which is the honest answer when
+  the reference genuinely does not identify a build. `:latest` is refused
+  outright as a version: reused, it gives every deploy the same container name
+  and leaves `CurrentHash == PreviousHash`, disabling rollback.
+
+- `plan` resolved the target version by the old rule, so it predicted container
+  names `deploy` would not create. It now uses the same resolution.
+
+### Added
+
+- `LogEntry.image`, so `teploy log` records the image a deploy actually ran.
+  The version alone could not be checked against anything, and the log is
+  precisely where a rollback target gets chosen. Omitted for entries with no
+  image (heal, lifecycle, static); old log lines parse unchanged.
+
+
 ### Added
 - `teploy lock status` — report the current deploy lock without touching it.
   Locks were writable from both ends (`deploy` takes an auto lock, `lock` takes

internal/cli/deploy.go

@@ -10,6 +10,7 @@ import (
 	"os"
 	"os/exec"
 	"os/signal"
+	"regexp"
 	"strings"
 	"time"
 
@@ -305,13 +306,24 @@ func deployAppConfig(flags *Flags, appCfg *config.AppConfig, serverName, image,
 	}
 
 	// 4. Resolve version.
+	//
+	// Order matters. An explicit --version always wins. Otherwise, when a
+	// prebuilt image is being deployed, the version comes from THE IMAGE, not
+	// from git: the image is what actually runs, and git HEAD is merely
+	// whatever the operator's working directory happened to be on. Only a
+	// build-from-source deploy falls through to the git hash, which is correct
+	// there because the source and the artifact are the same thing.
 	if version == "" {
-		version, err = gitShortHash()
-		if err != nil {
-			if image != "" {
-				// Pre-built image with no git repo — use a timestamp.
+		if image != "" {
+			version = versionFromImage(image)
+			if version == "" {
+				// A floating or digest-less reference carries no usable
+				// version; a timestamp is at least unique per deploy.
 				version = fmt.Sprintf("%d", time.Now().Unix())
-			} else {
+			}
+		} else {
+			version, err = gitShortHash()
+			if err != nil {
 				return fmt.Errorf("could not determine version from git: %w (use --version flag)", err)
 			}
 		}
@@ -645,6 +657,58 @@ func deployBuiltImage(ctx context.Context, executor ssh.Executor, appCfg *config
 	return nil
 }
 
+// imageTagPattern is Docker's tag grammar. Version strings are interpolated
+// UNQUOTED into remote shell commands via ContainerName (docker rename, docker
+// rm -f), and until now a version could only come from git output or an
+// operator's own --version. Deriving it from an image reference introduces a
+// less-trusted source, so it is gated here rather than trusted.
+var imageTagPattern = regexp.MustCompile(`^[A-Za-z0-9_][A-Za-z0-9._-]{0,127}$`)
+
+// versionFromImage derives a deploy version from an image reference, or ""
+// when the reference carries no meaningful one.
+//
+// Why this exists: `teploy deploy --image repo/app:462d7a7` used to label the
+// deploy with the local git HEAD instead — so the container name, `teploy log`
+// and the operator's screen all asserted a commit whose code was not running.
+// Observed in production as "Deployed version fe82bf0" while running the image
+// tagged 462d7a7. During a rollback that is worse than cosmetic: the version
+// someone picks out of the log never corresponded to that image.
+//
+// Note this is NOT specific to the --image flag. The caller resolves
+// `image = appCfg.Image` first, so a teploy.yml pinning a prebuilt image hit
+// the identical problem with no flag passed.
+func versionFromImage(image string) string {
+	// A digest pins exact content, so it is the most truthful label available,
+	// and it wins over any tag beside it: Docker resolves the digest and
+	// ignores the tag, so labelling `repo:1.2.3@sha256:...` as 1.2.3 would be
+	// the same class of lie this function exists to remove.
+	if _, digest, ok := strings.Cut(image, "@"); ok {
+		const prefix = "sha256:"
+		if strings.HasPrefix(digest, prefix) && len(digest) == len(prefix)+64 {
+			// Colons are invalid in a container name, so the prefix is dashed.
+			return "sha256-" + digest[len(prefix):len(prefix)+12]
+		}
+		return ""
+	}
+
+	// The tag follows the last ':', but only when that colon comes after the
+	// last '/' — otherwise a registry port (100.108.123.49:49152/tyler/app)
+	// parses as the tag.
+	tag := ""
+	if i := strings.LastIndex(image, ":"); i > strings.LastIndex(image, "/") {
+		tag = image[i+1:]
+	}
+
+	// "" and "latest" are refused deliberately. A floating tag reused as the
+	// version gives every deploy the same container name AND leaves
+	// CurrentHash == PreviousHash, which disables rollback entirely. The
+	// caller's timestamp fallback is at least unique per deploy.
+	if tag == "" || tag == "latest" || !imageTagPattern.MatchString(tag) {
+		return ""
+	}
+	return tag
+}
+
 // runMultiDeploy handles deploying to multiple servers in parallel.
 func runMultiDeploy(flags *Flags, appCfg *config.AppConfig, image, version string, skipDNSCheck bool, parallel int, migrateVolumes bool) error {
 	// Resolve parallel setting.

internal/cli/plan.go

@@ -128,18 +128,23 @@ func runPlan(flags *Flags, version string) error {
 		return planStatic(ctx, flags, appCfg, executor)
 	}
 
-	// Resolve the target version exactly as `deploy` does: --version wins, else
-	// the local git short hash. When neither is available (no git repo) but a
-	// pre-built image is configured, deploy falls back to a timestamp — a
-	// non-deterministic version — so we fall back to an indicative diff.
+	// Resolve the target version exactly as `deploy` does — and it has to stay
+	// exactly, or plan predicts container names the deploy will not create.
+	// --version wins; else a prebuilt image supplies it; else the git hash.
+	// A floating tag (:latest, untagged) yields a timestamp at deploy time,
+	// which is non-deterministic, so the diff can only be indicative.
 	versionKnown := true
 	if version == "" {
-		version, err = gitShortHash()
-		if err != nil {
-			if appCfg.Image == "" {
+		if appCfg.Image != "" {
+			version = versionFromImage(appCfg.Image)
+			if version == "" {
+				versionKnown = false
+			}
+		} else {
+			version, err = gitShortHash()
+			if err != nil {
 				return fmt.Errorf("could not determine target version from git: %w (pass --version)", err)
 			}
-			versionKnown = false
 		}
 	}
 

internal/cli/version_from_image_test.go

@@ -0,0 +1,89 @@
+package cli
+
+import "testing"
+
+// The bug this guards: `teploy deploy --image repo/app:462d7a7` labelled the
+// deploy with the local git HEAD (fe82bf0), so the container name, the deploy
+// log and the operator's screen all named a commit whose code was not running.
+func TestVersionFromImage(t *testing.T) {
+	cases := []struct {
+		name  string
+		image string
+		want  string
+	}{
+		{
+			// The production case. The registry port contains a colon, so a
+			// naive "text after the last colon" split returns the wrong thing
+			// for a registry-qualified reference without a tag.
+			name:  "registry with port and tag",
+			image: "100.108.123.49:49152/tyler/fylun-web:462d7a7",
+			want:  "462d7a7",
+		},
+		{name: "simple tag", image: "nginx:1.25", want: "1.25"},
+		{name: "namespaced tag", image: "black-forest-labs/flux:v2", want: "v2"},
+
+		// A registry port must not be mistaken for a tag.
+		{name: "registry port, no tag", image: "100.108.123.49:49152/tyler/app", want: ""},
+		{name: "untagged", image: "nginx", want: ""},
+
+		// Reusing a floating tag as the version gives every deploy the same
+		// container name and leaves CurrentHash == PreviousHash, which disables
+		// rollback. The caller falls back to a timestamp instead.
+		{name: "latest is refused", image: "nginx:latest", want: ""},
+
+		// A digest is content-addressed and the most truthful label available.
+		// Colons are invalid in container names, hence the dashed prefix.
+		{
+			name:  "digest",
+			image: "repo/app@sha256:" + "ab12cd34ef56" + "0000000000000000000000000000000000000000000000000000",
+			want:  "sha256-ab12cd34ef56",
+		},
+		{
+			// Docker resolves the digest and ignores the tag, so labelling this
+			// "1.2.3" would be the same lie this function exists to remove.
+			name:  "digest wins over an accompanying tag",
+			image: "repo/app:1.2.3@sha256:" + "ab12cd34ef56" + "0000000000000000000000000000000000000000000000000000",
+			want:  "sha256-ab12cd34ef56",
+		},
+		{name: "malformed digest", image: "repo/app@sha256:tooshort", want: ""},
+
+		// Versions are interpolated UNQUOTED into remote docker commands via
+		// ContainerName, and an image reference is a less-trusted source than
+		// git output. Anything outside Docker's tag grammar is refused.
+		{name: "shell metacharacters refused", image: "repo/app:v1;rm -rf /", want: ""},
+		{name: "backtick refused", image: "repo/app:`whoami`", want: ""},
+		{name: "leading dot refused", image: "repo/app:.hidden", want: ""},
+		{name: "empty", image: "", want: ""},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			if got := versionFromImage(tc.image); got != tc.want {
+				t.Errorf("versionFromImage(%q) = %q, want %q", tc.image, got, tc.want)
+			}
+		})
+	}
+}
+
+// Every accepted version must be safe to concatenate into a container name and
+// into the remote shell commands that manipulate it.
+func TestVersionFromImage_OutputIsContainerNameSafe(t *testing.T) {
+	images := []string{
+		"100.108.123.49:49152/tyler/fylun-web:462d7a7",
+		"nginx:1.25",
+		"repo/app@sha256:ab12cd34ef560000000000000000000000000000000000000000000000000000",
+	}
+	for _, image := range images {
+		v := versionFromImage(image)
+		if v == "" {
+			t.Fatalf("expected a version for %q", image)
+		}
+		for _, r := range v {
+			ok := (r >= 'a' && r <= 'z') || (r >= 'A' && r <= 'Z') ||
+				(r >= '0' && r <= '9') || r == '.' || r == '_' || r == '-'
+			if !ok {
+				t.Errorf("versionFromImage(%q) = %q contains %q, unsafe in a container name", image, v, r)
+			}
+		}
+	}
+}

internal/state/state.go

@@ -103,6 +103,14 @@ type LogEntry struct {
 	Success    bool      `json:"success"`
 	DurationMs int64     `json:"duration_ms"`
 	Message    string    `json:"message,omitempty"`
+	// Image the deploy actually ran, when one was known.
+	//
+	// The version alone was not enough: a deploy labelled with a version that
+	// did not come from the image it ran could not be told apart afterwards,
+	// and `teploy log` is exactly where a rollback target gets chosen. Omitted
+	// for entries with no image (heal, lifecycle, static), so old log lines
+	// parse unchanged.
+	Image string `json:"image,omitempty"`
 }
 
 // Read reads canonical v2 state first. A missing v2 file falls back to the