feat(admin): show the deployed commit and build time in the admin (#233)

There was no way to tell which build an environment was running. That is not hypothetical: minutes after #232 merged, `npm run backfill:images` in QA failed with `tsx: not found` because the container was still serving the pre-merge image, and the only thing that revealed it was npm echoing the old script line. Had the change been anywhere other than a package.json script, the container would have looked healthy while running the wrong code. The header now reads something like `a5076cc · built 29 Aug 20:36`. The commit answers "is this the code I expect"; the build time answers "did my redeploy actually rebuild", which is a different question and the one that would have caught the case above. The commit is read out of `.git` directly rather than by shelling out, because node:20-bookworm-slim has no git binary and adding an apt layer so the image can print seven characters is a poor trade. `.git` is copied into the build stage only — verified absent from the final image — so no repository history reaches a deployed container. Resolution is pure and separately tested across every shape that actually occurs: a detached HEAD holding the object name, which is what a checkout of a ref produces; a symbolic HEAD followed to a loose ref file; the same followed to packed-refs, which is what a fresh clone commonly has; peeled `^` tag lines ignored so an annotated tag cannot yield the wrong commit; and every failure path returning `unknown`. That last part is the one that matters most — this runs during a Docker build, and a version stamp must never be the thing that stops a deploy. Served from a gated /api/admin/version rather than folded into /api/config. That endpoint is public, and a commit hash there would tell any storefront visitor exactly which revision of a public repository is deployed. An integration test asserts the gate and asserts the public config does not carry it, because the boundary is the whole point rather than an implementation detail. Verified in the built image rather than argued: the stamp inside it reads a5076cc, matching `git rev-parse --short HEAD`, and a running container serves it from /api/admin/version while /api/config returns only what it did before. Backend: 296 unit, 263 integration, tsc clean, lint unchanged at six pre-existing warnings. Frontend builds clean with its two pre-existing warnings untouched. Closes #233
2026-08-29 15:37:12 -05:00
parent a5076cc217
commit 44328d0b5c
9 changed files with 499 additions and 1 deletions
@@ -0,0 +1,109 @@
+import { resolveCommit, GitSource, UNKNOWN_COMMIT } from '../../src/buildInfo';
+
+// A source with nothing in it, so each test states only the files it cares
+// about. Every field is deliberately explicit — a missing `.git` is a normal
+// case here, not an edge one, and it has to be as easy to write as the others.
+function source(overrides: Partial<GitSource> = {}): GitSource {
+  return {
+    head: null,
+    readRef: () => null,
+    packedRefs: null,
+    ...overrides
+  };
+}
+
+const SHA = '846646f7ec8ec0087ec1d89bcee8ab1865b57a7a';
+
+describe('resolveCommit', () => {
+  // What a fresh clone at a specific commit looks like — Portainer checks out
+  // a ref, and a detached HEAD holds the SHA with no indirection at all.
+  it('reads a detached HEAD directly', () => {
+    expect(resolveCommit(source({ head: `${SHA}\n` }))).toBe('846646f');
+  });
+
+  // What a working checkout looks like, including this repository.
+  it('follows a symbolic HEAD to its ref file', () => {
+    expect(
+      resolveCommit(
+        source({
+          head: 'ref: refs/heads/main\n',
+          readRef: (ref) => (ref === 'refs/heads/main' ? `${SHA}\n` : null)
+        })
+      )
+    ).toBe('846646f');
+  });
+
+  // A ref that has been packed has no loose file. Without this the common case
+  // of a freshly cloned repository resolves to unknown.
+  it('falls back to packed-refs when the ref file is absent', () => {
+    expect(
+      resolveCommit(
+        source({
+          head: 'ref: refs/heads/main\n',
+          packedRefs: `# pack-refs with: peeled fully-peeled sorted\n${SHA} refs/heads/main\n`
+        })
+      )
+    ).toBe('846646f');
+  });
+
+  it('picks the right entry out of a packed-refs with many', () => {
+    const other = 'ffffffffffffffffffffffffffffffffffffffff';
+    expect(
+      resolveCommit(
+        source({
+          head: 'ref: refs/heads/main\n',
+          packedRefs:
+            `# pack-refs with: peeled fully-peeled sorted\n` +
+            `${other} refs/heads/other\n` +
+            `${SHA} refs/heads/main\n` +
+            `${other} refs/tags/v1\n`
+        })
+      )
+    ).toBe('846646f');
+  });
+
+  // Annotated tags write a second `^<sha>` line for the object the tag points
+  // at. It is not a ref line and must not be mistaken for one.
+  it('ignores peeled tag lines in packed-refs', () => {
+    expect(
+      resolveCommit(
+        source({
+          head: 'ref: refs/tags/v1\n',
+          packedRefs:
+            `${SHA} refs/tags/v1\n` + `^ffffffffffffffffffffffffffffffffffffffff\n`
+        })
+      )
+    ).toBe('846646f');
+  });
+
+  // Every failure below returns UNKNOWN rather than throwing. This runs during
+  // a Docker build; a version stamp must never be the thing that stops a deploy.
+  it('is unknown when there is no .git at all', () => {
+    expect(resolveCommit(source())).toBe(UNKNOWN_COMMIT);
+  });
+
+  it('is unknown when the ref resolves to nothing', () => {
+    expect(resolveCommit(source({ head: 'ref: refs/heads/main\n' }))).toBe(UNKNOWN_COMMIT);
+  });
+
+  it('is unknown when packed-refs does not mention the ref', () => {
+    expect(
+      resolveCommit(
+        source({
+          head: 'ref: refs/heads/gone\n',
+          packedRefs: `${SHA} refs/heads/main\n`
+        })
+      )
+    ).toBe(UNKNOWN_COMMIT);
+  });
+
+  // A HEAD that is neither a ref line nor a SHA. Returning it verbatim would
+  // put arbitrary file contents on the admin screen.
+  it('is unknown when HEAD is not something it recognises', () => {
+    expect(resolveCommit(source({ head: 'not a sha and not a ref\n' }))).toBe(UNKNOWN_COMMIT);
+  });
+
+  it('is unknown when HEAD is empty', () => {
+    expect(resolveCommit(source({ head: '   \n' }))).toBe(UNKNOWN_COMMIT);
+  });
+});