fix: attribute Sentry errors to the loaded source release (#13719)

Attribute optional server and browser Sentry events to their source build.
Use validated build commits for Docker and source/npm artifacts, preserve
explicit server release overrides, and keep cached browser bundles tied
to the commit they loaded.

Verify 127 focused tests, server/UI typechecks, Docker and source build
stamps, all 53 CI checks, and Greptile 5/5 with no unresolved comments.

Co-Authored-By: Paperclip <noreply@paperclip.ing>
This commit is contained in:
Devin FoleyandPaperclip authored and GitHub committed 2026-09-20 08:08:33 -07:00
1 parent 2a99de80ec
commit 600e552d7b
14 files changed
+268 -10

No files matched your search

+22
View File
@@ -15,6 +15,28 @@ describe("parseBuildCommit", () => {
});
describe("readBuildCommit", () => {
it("reads the built server stamp in npm packages without a deployment marker", () => {
const commit = "0123456789abcdef0123456789abcdef01234567";
expect(readBuildCommit({
environmentCommit: null,
buildCommitPath: "/app/.paperclip-build-commit",
buildInfoPath: "/app/server/dist/build-info.json",
readTextFile: (path) => {
if (path.endsWith(".paperclip-build-commit")) throw new Error("ENOENT");
return JSON.stringify({ commit });
},
})).toBe(commit);
});
it.each(["invalid json", "null", '{"commit":"short"}', '{"commit":42}'])(
"fails open on an invalid server stamp: %s", (stamp) => {
expect(readBuildCommit({
environmentCommit: null,
readTextFile: () => stamp,
})).toBeNull();
},
);
it("prefers an explicit environment commit", () => {
const readTextFile = vi.fn(() => "ffffffffffffffffffffffffffffffffffffffff");
+58
View File
@@ -268,6 +268,13 @@ describe("missing @sentry/node package", () => {
it("logs one warning and resolves", async () => {
process.env[BACKEND_DSN_ENV] = "https://public@o0.ingest.sentry.io/1";
const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
// Keep this failure-mode test valid when the optional real-SDK tests run.
vi.doMock("../peer-version-check.js", () => ({
checkExactPeerVersions: () => ({
ok: false,
detail: { missing: ["@sentry/node"], mismatched: [] },
}),
}));
const { sentryReady } = await importFreshSentry();
@@ -537,6 +544,41 @@ describe("buildSentryInitOptions serverName", () => {
});
});
describe("buildSentryInitOptions release", () => {
const commit = "0123456789abcdef0123456789abcdef01234567";
const integrations = {
httpIntegration: () => ({ name: "Http" }),
onUnhandledRejectionIntegration: () => ({ name: "OnUnhandledRejection" }),
};
beforeEach(() => {
vi.stubEnv("SENTRY_RELEASE", "");
vi.doMock("../build-commit.js", () => ({ readBuildCommit: () => commit }));
});
afterEach(() => {
vi.unstubAllEnvs();
vi.doUnmock("../build-commit.js");
});
it("uses the server build commit", async () => {
const { buildSentryInitOptions } = await importFreshSentry();
expect(buildSentryInitOptions("test-dsn", integrations).release).toBe(commit);
});
it("preserves an operator's explicit release", async () => {
vi.stubEnv("SENTRY_RELEASE", " custom-release ");
const { buildSentryInitOptions } = await importFreshSentry();
expect(buildSentryInitOptions("test-dsn", integrations).release).toBe("custom-release");
});
it("leaves an unknown build unattributed", async () => {
vi.doMock("../build-commit.js", () => ({ readBuildCommit: () => null }));
const { buildSentryInitOptions } = await importFreshSentry();
expect(buildSentryInitOptions("test-dsn", integrations).release).toBeUndefined();
});
});
describe("with @sentry/node mocked", () => {
it("initializes the client and shares captureException / shutdownSentry with it", async () => {
process.env[DSN_ENV] = "https://public@o0.ingest.sentry.io/1";
@@ -644,6 +686,22 @@ describe.skipIf(!sentryPackage)("captured event shape against the real @sentry/n
Sentry.init(options);
}
it("attaches the actual build commit to an emitted event", async () => {
const commit = "0123456789abcdef0123456789abcdef01234567";
vi.stubEnv("PAPERCLIP_BUILD_COMMIT", commit);
vi.stubEnv("SENTRY_RELEASE", "");
try {
let captured: Record<string, unknown> | null = null;
await initRealSentryForTest((event) => { captured = event; });
sentryPackage!.captureException(new Error("build attribution check"));
await sentryPackage!.flush(2000);
expect(captured).toMatchObject({ release: commit });
expect(captured).not.toHaveProperty("request");
} finally {
vi.unstubAllEnvs();
}
});
it("a server event captured after a console.error call carries no console breadcrumb", async () => {
const Sentry = sentryPackage!;
let captured: Record<string, unknown> | null = null;
@@ -1,7 +1,32 @@
import { describe, expect, it } from "vitest";
import { execFileSync } from "node:child_process";
import { copyFileSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { resolveBuildCommit } from "../../scripts/write-build-stamp.mjs";
it("packages a full source commit without a Docker build argument", () => {
const root = realpathSync(mkdtempSync(join(tmpdir(), "paperclip-build-stamp-")));
try {
const scriptDir = join(root, "server", "scripts");
mkdirSync(scriptDir, { recursive: true });
const script = join(scriptDir, "write-build-stamp.mjs");
copyFileSync(new URL("../../scripts/write-build-stamp.mjs", import.meta.url), script);
const git = (...args: string[]) => execFileSync("git", args, { cwd: root, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trim();
git("init", "--quiet");
git("-c", "user.name=Test", "-c", "user.email=test@example.invalid", "commit", "--allow-empty", "--no-gpg-sign", "-m", "fixture");
const env = { ...process.env };
delete env.PAPERCLIP_BUILD_COMMIT;
execFileSync(process.execPath, [script], { cwd: root, env, stdio: "pipe" });
const stamp = JSON.parse(readFileSync(join(root, "server", "dist", "build-info.json"), "utf8"));
expect(stamp.commit).toBe(git("rev-parse", "HEAD"));
expect(stamp.commit).toMatch(/^[0-9a-f]{40}$/);
} finally {
rmSync(root, { recursive: true, force: true });
}
});
describe("resolveBuildCommit", () => {
it("prefers the git commit over the supplied environment commit", () => {
expect(resolveBuildCommit("aaaaaaa", "bbbbbbb")).toBe("aaaaaaa");
+9 -2
View File
@@ -7,6 +7,7 @@ const FULL_SHA_RE = /^[0-9a-f]{40}$/i;
const DEFAULT_BUILD_COMMIT_PATH = fileURLToPath(
new URL("../../.paperclip-build-commit", import.meta.url),
);
const DEFAULT_BUILD_INFO_PATH = fileURLToPath(new URL("./build-info.json", import.meta.url));
export function parseBuildCommit(value: string | null | undefined): string | null {
const commit = value?.trim() ?? "";
@@ -17,6 +18,7 @@ export function readBuildCommit(
opts: {
environmentCommit?: string | null;
buildCommitPath?: string;
buildInfoPath?: string;
readTextFile?: ReadTextFile;
} = {},
): string | null {
@@ -27,9 +29,14 @@ export function readBuildCommit(
);
if (environmentCommit) return environmentCommit;
const readTextFile = opts.readTextFile ?? ((path: string) => readFileSync(path, "utf8"));
try {
const readTextFile = opts.readTextFile ?? ((path: string) => readFileSync(path, "utf8"));
return parseBuildCommit(readTextFile(opts.buildCommitPath ?? DEFAULT_BUILD_COMMIT_PATH));
const markerCommit = parseBuildCommit(readTextFile(opts.buildCommitPath ?? DEFAULT_BUILD_COMMIT_PATH));
if (markerCommit) return markerCommit;
} catch { /* The deployment marker is absent in npm packages. */ }
try {
const stamp = JSON.parse(readTextFile(opts.buildInfoPath ?? DEFAULT_BUILD_INFO_PATH));
return typeof stamp?.commit === "string" ? parseBuildCommit(stamp.commit) : null;
} catch {
return null;
}
+4 -1
View File
@@ -56,6 +56,7 @@
// `instrumentation.ts`.
import os from "node:os";
import { readBuildCommit } from "./build-commit.js";
import { checkExactPeerVersions } from "./peer-version-check.js";
import { resolveSentryDsns } from "./sentry-dsn.js";
@@ -200,12 +201,13 @@ export function shutdownSentry(): Promise<void> {
*/
interface SentryModuleLike {
httpIntegration(options: { breadcrumbs: boolean }): { name: string };
onUnhandledRejectionIntegration(options: { mode: string }): { name: string };
onUnhandledRejectionIntegration(options: { mode: "strict" }): { name: string };
}
/** The `Sentry.init` options this gate builds. */
export interface SentryInitOptions {
dsn: string;
release?: string;
skipOpenTelemetrySetup: boolean;
tracesSampleRate: number;
sendDefaultPii: boolean;
@@ -225,6 +227,7 @@ export function buildSentryInitOptions(
): SentryInitOptions {
return {
dsn,
release: process.env.SENTRY_RELEASE?.trim() || readBuildCommit() || undefined,
skipOpenTelemetrySetup: true,
tracesSampleRate: 0,
sendDefaultPii: false,