Skip to content

The open-source app everyone uses to manage agents at work

fix(server): stamp the real build version into images instead of the package.json placeholder (#10257)

Devin Foleyd1b9448b57a8
diff --git a/.github/workflows/docker.yml b/.github/workflows/docker.yml
index 1cf0640c62..66c505e3f8 100644
--- a/.github/workflows/docker.yml
+++ b/.github/workflows/docker.yml
@@ -21,6 +21,24 @@ jobs:
steps:
- name: Checkout
uses: actions/checkout@v7
+ with:
+ # Full history and tags so `git describe` below can compute the
+ # release version to stamp into the image.
+ fetch-depth: 0
+
+ # `.git` is dockerignored, so a running image cannot derive its own
+ # version and otherwise reports the source package.json placeholder in
+ # analytics and the debug panel. Compute it here from the pristine
+ # checkout (real CalVer drift from the nearest release tag) and pass it
+ # into both builds. Empty when no release tag is reachable — the server
+ # then keeps its existing fallbacks.
+ - name: Compute build version
+ id: build-version
+ run: |
+ set -euo pipefail
+ version="$(git describe --tags --match 'v*' --long --dirty 2>/dev/null || true)"
+ echo "version=${version}" >> "$GITHUB_OUTPUT"
+ echo "Stamping build version: ${version:-<none>}"
- name: Setup pnpm
uses: pnpm/action-setup@v6
@@ -124,6 +142,8 @@ jobs:
# the Dockerfile now declares a later `cloud` stage, and without a
# target the default would silently become that stage.
target: production
+ build-args: |
+ PAPERCLIP_BUILD_VERSION=${{ steps.build-version.outputs.version }}
platforms: linux/amd64,linux/arm64
push: true
cache-from: type=gha
@@ -161,6 +181,7 @@ jobs:
# the variant; add here when managed deployments need another.
build-args: |
CLOUD_BUNDLED_PLUGINS=daytona
+ PAPERCLIP_BUILD_VERSION=${{ steps.build-version.outputs.version }}
platforms: linux/amd64,linux/arm64
push: true
cache-from: type=gha
diff --git a/Dockerfile b/Dockerfile
index e6a3cba9d1..7793c247fe 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -59,6 +59,10 @@ RUN test -f server/dist/index.js || (echo "ERROR: server build output missing" &
FROM base AS production
ARG USER_UID=1000
ARG USER_GID=1000
+# Real version for this build, computed from `git describe` on the CI runner
+# (the image has no .git, so the server cannot derive it at runtime). Empty for
+# local `docker build`, which just leaves the server on its normal fallbacks.
+ARG PAPERCLIP_BUILD_VERSION=""
WORKDIR /app
COPY --chown=node:node --from=build /app /app
RUN npm install --global --omit=dev @anthropic-ai/claude-code@latest @openai/codex@latest opencode-ai @google/gemini-cli@latest \
@@ -78,6 +82,7 @@ ENV NODE_ENV=production \
SERVE_UI=true \
PAPERCLIP_HOME=/paperclip \
PAPERCLIP_INSTANCE_ID=default \
+ PAPERCLIP_BUILD_VERSION=${PAPERCLIP_BUILD_VERSION} \
USER_UID=${USER_UID} \
USER_GID=${USER_GID} \
PAPERCLIP_CONFIG=/paperclip/instances/default/config.json \
diff --git a/server/src/__tests__/build-version.test.ts b/server/src/__tests__/build-version.test.ts
new file mode 100644
index 0000000000..9bf122583c
--- /dev/null
+++ b/server/src/__tests__/build-version.test.ts
@@ -0,0 +1,58 @@
+import { describe, expect, it, vi } from "vitest";
+import { parseBuildVersion, readBuildVersion } from "../build-version.js";
+
+describe("parseBuildVersion", () => {
+ it("trims a stamped git describe string", () => {
+ expect(parseBuildVersion(" v2026.722.0-15-g4c55f0d\n")).toBe("v2026.722.0-15-g4c55f0d");
+ });
+
+ it("accepts an already-resolved version verbatim", () => {
+ expect(parseBuildVersion("2026.725.0-canary.2")).toBe("2026.725.0-canary.2");
+ });
+
+ it("rejects empty and whitespace-bearing values", () => {
+ expect(parseBuildVersion("")).toBeNull();
+ expect(parseBuildVersion(" ")).toBeNull();
+ expect(parseBuildVersion("v1 with spaces")).toBeNull();
+ expect(parseBuildVersion(null)).toBeNull();
+ expect(parseBuildVersion(undefined)).toBeNull();
+ });
+});
+
+describe("readBuildVersion", () => {
+ it("prefers an explicit environment version over the file", () => {
+ const readTextFile = vi.fn(() => "v9999.0.0-0-g0000000");
+
+ expect(
+ readBuildVersion({
+ environmentVersion: "v2026.722.0-15-g4c55f0d",
+ readTextFile,
+ }),
+ ).toBe("v2026.722.0-15-g4c55f0d");
+ expect(readTextFile).not.toHaveBeenCalled();
+ });
+
+ it("reads the build marker when no environment version is set", () => {
+ expect(
+ readBuildVersion({
+ environmentVersion: null,
+ buildVersionPath: "/app/.paperclip-build-version",
+ readTextFile: (path) => {
+ expect(path).toBe("/app/.paperclip-build-version");
+ return "v2026.722.0-15-g4c55f0d\n";
+ },
+ }),
+ ).toBe("v2026.722.0-15-g4c55f0d");
+ });
+
+ it("returns null when neither the environment nor the file provides a version", () => {
+ expect(
+ readBuildVersion({
+ environmentVersion: null,
+ readTextFile: () => {
+ throw new Error("ENOENT");
+ },
+ }),
+ ).toBeNull();
+ });
+});
diff --git a/server/src/__tests__/version.test.ts b/server/src/__tests__/version.test.ts
index d6d717d8e6..c3e05f95e8 100644
--- a/server/src/__tests__/version.test.ts
+++ b/server/src/__tests__/version.test.ts
@@ -101,6 +101,7 @@ describe("resolveServerVersion", () => {
it("uses deployment commit metadata when a source build has no git directory", () => {
expect(
resolveServerVersion({
+ buildVersion: null,
buildCommit: "0123456789abcdef0123456789abcdef01234567",
packageVersion: "2026.706.0",
gitDescribeCommand: () => {
@@ -111,6 +112,66 @@ describe("resolveServerVersion", () => {
).toBe("2026.706.0+0.git.0123456");
});
+ it("uses the stamped build version when a Docker image has no git directory", () => {
+ const debugLog = vi.fn();
+
+ expect(
+ resolveServerVersion({
+ // A real CalVer describe stamped by CI wins over the coarse build-commit
+ // stamp and the source placeholder — this is the analytics/debug-panel fix.
+ buildVersion: "v2026.722.0-15-g4c55f0d",
+ buildCommit: "0123456789abcdef0123456789abcdef01234567",
+ packageVersion: "0.3.1",
+ gitDescribeCommand: () => {
+ throw new Error("fatal: not a git repository");
+ },
+ debugLog,
+ }),
+ ).toBe("2026.722.0+15.git.4c55f0d");
+ expect(debugLog).toHaveBeenCalledWith(
+ { reason: "build_version" },
+ "using stamped build version for server version",
+ );
+ });
+
+ it("collapses an on-tag stamped build version to the release version", () => {
+ expect(
+ resolveServerVersion({
+ buildVersion: "v2026.722.0-0-g4c55f0d",
+ packageVersion: "0.3.1",
+ gitDescribeCommand: () => {
+ throw new Error("no git");
+ },
+ debugLog: vi.fn(),
+ }),
+ ).toBe("2026.722.0");
+ });
+
+ it("uses a pre-resolved stamped build version verbatim", () => {
+ expect(
+ resolveServerVersion({
+ buildVersion: "2026.725.0-canary.2",
+ packageVersion: "0.3.1",
+ gitDescribeCommand: () => {
+ throw new Error("no git");
+ },
+ debugLog: vi.fn(),
+ }),
+ ).toBe("2026.725.0-canary.2");
+ });
+
+ it("keeps the live git-derived version even when a build version is stamped", () => {
+ expect(
+ resolveServerVersion({
+ // A stamped version is only a fallback: a real checkout's git describe wins.
+ buildVersion: "v2020.1.1-0-g0000000",
+ packageVersion: "0.3.1",
+ gitDescribeCommand: () => "v2026.626.0-58-g518fc71ce\n",
+ debugLog: vi.fn(),
+ }),
+ ).toBe("2026.626.0+58.git.518fc71ce");
+ });
+
it("skips git metadata probing for packaged installs under node_modules", () => {
const debugLog = vi.fn();
diff --git a/server/src/build-version.ts b/server/src/build-version.ts
new file mode 100644
index 0000000000..f0938e739c
--- /dev/null
+++ b/server/src/build-version.ts
@@ -0,0 +1,45 @@
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+type ReadTextFile = (path: string) => string;
+
+// The build version stamp is computed by CI on the build runner (where `.git`
+// exists) and baked into the image, so a running container reports the real
+// version instead of the source `package.json` placeholder. It is typically the
+// raw `git describe` output, e.g. "v2026.722.0-15-g4c55f0d"; version.ts runs it
+// through the same parser used for a live checkout. A resolved version set
+// directly is accepted verbatim.
+const DEFAULT_BUILD_VERSION_PATH = fileURLToPath(
+ new URL("../../.paperclip-build-version", import.meta.url),
+);
+
+export function parseBuildVersion(value: string | null | undefined): string | null {
+ const version = value?.trim() ?? "";
+ // A version/describe string is a single token: reject empties and anything
+ // carrying whitespace so a stray file cannot inject a multi-line value.
+ if (!version || /\s/.test(version)) return null;
+ return version;
+}
+
+export function readBuildVersion(
+ opts: {
+ environmentVersion?: string | null;
+ buildVersionPath?: string;
+ readTextFile?: ReadTextFile;
+ } = {},
+): string | null {
+ const environmentVersion = parseBuildVersion(
+ opts.environmentVersion === undefined
+ ? process.env.PAPERCLIP_BUILD_VERSION
+ : opts.environmentVersion,
+ );
+ if (environmentVersion) return environmentVersion;
+
+ try {
+ const readTextFile =
+ opts.readTextFile ?? ((path: string) => readFileSync(path, "utf8"));
+ return parseBuildVersion(readTextFile(opts.buildVersionPath ?? DEFAULT_BUILD_VERSION_PATH));
+ } catch {
+ return null;
+ }
+}
diff --git a/server/src/version.ts b/server/src/version.ts
index 525c2e2697..6627637b02 100644
--- a/server/src/version.ts
+++ b/server/src/version.ts
@@ -3,6 +3,7 @@ import { execFileSync } from "node:child_process";
import { existsSync, realpathSync } from "node:fs";
import { basename, dirname, join } from "node:path";
import { parseBuildCommit, readBuildCommit } from "./build-commit.js";
+import { parseBuildVersion, readBuildVersion } from "./build-version.js";
type PackageJson = {
version?: string;
@@ -149,6 +150,7 @@ export function parseGitDescribeVersion(output: string): string | null {
export function resolveServerVersion(
opts: {
buildCommit?: string | null;
+ buildVersion?: string | null;
gitDescribeCommand?: GitDescribeCommand;
packageVersion?: string;
debugLog?: DebugLog;
@@ -191,6 +193,23 @@ export function resolveServerVersion(
);
}
+ // Prefer a version stamped into the build. A Docker image has no `.git`, so
+ // the git describe above cannot run; CI computes the version on the build
+ // runner and bakes it in, carrying the real CalVer instead of the source
+ // placeholder. Parsed with the same rules as a live checkout, so both report
+ // the same string. Falls through to the coarser build-commit stamp when unset.
+ const buildVersion =
+ opts.buildVersion === undefined
+ ? readBuildVersion()
+ : parseBuildVersion(opts.buildVersion);
+ if (buildVersion) {
+ debugLog(
+ { reason: "build_version" },
+ "using stamped build version for server version",
+ );
+ return parseGitDescribeVersion(buildVersion) ?? buildVersion;
+ }
+
const buildCommit =
opts.buildCommit === undefined
? readBuildCommit()