Expose the running build commit on the unauthenticated health response (#10563)
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - Instances run self-hosted or under hosting/deploy tooling, and operators need to observe what build a server is actually running > - `/api/health` carries the git SHA only inside `serverInfo`, which is gated to board/agent actors — anonymous callers get a redacted body with no version signal at all > - Deploy tooling that manages instances from outside (fleet rollouts, hosting providers, upgrade scripts) therefore cannot ground-truth that a deploy actually shipped without holding credentials > - A build commit is a plain git SHA of this public repository — it is not a secret, and gating it buys no security while blocking legitimate verification > - This pull request surfaces the running build commit as a top-level `commit` field on every `/api/health` response, including the redacted anonymous one > - The benefit is credential-free deploy verification: any operator or tool can confirm which commit an instance serves, while the fuller `serverInfo` block stays access-controlled as before ## Linked Issues or Issue Description No existing public issue — inline description following the feature request template: **Subsystem affected** Server (API, runs, routes) **Problem or motivation** An anonymous `GET /api/health` returns a redacted body with no version information; the running git SHA exists only in `serverInfo.git.fullSha`, which requires a board/agent actor. External deploy tooling (fleet rollouts, hosting providers, upgrade scripts) therefore cannot verify that an instance is actually serving the build it was just upgraded to — a rollout that silently keeps running the old image is indistinguishable from a successful one at the health endpoint. **Proposed solution** Surface the running build commit as a top-level nullable `commit` field on every `/api/health` response shape, including the redacted anonymous one, while keeping the fuller `serverInfo` block access-controlled as before. A build commit is a plain git SHA of this public repository — exposing it costs nothing and enables credential-free deploy verification, like the `version` endpoints on most server software. **Alternatives considered** Authenticating deploy tooling as a board actor to read `serverInfo` — rejected: it forces credential plumbing into infrastructure that only needs a public SHA, and adds a whole class of auth-misconfiguration failure to deploy verification. **Roadmap alignment** Not on ROADMAP.md; a small operational observability improvement, no overlap with planned core work. ## What Changed - `server/src/routes/health.ts`: derive `commit` from the server info snapshot (`serverInfo.git.fullSha` when git metadata is available, else `null`) and include it as a top-level field on every `/api/health` response shape — the redacted anonymous body, the full-details body, the no-db body, and the 503 database-unreachable body. - `serverInfo` itself remains gated to full-details responses exactly as before; only the bare commit is newly public. - `server/src/__tests__/health.test.ts`: updated exact-shape assertions to include `commit`, and added an assertion that `commit` is `null` (not omitted) when git metadata is unavailable. The redacted-response tests now pin that anonymous callers receive the commit. ## Verification - `pnpm vitest run src/__tests__/health.test.ts` in `server/` — 13 tests pass, including the redacted-anonymous shapes (which now pin the `commit` field) and the git-unavailable `null` case. - `tsc -p server/tsconfig.json --noEmit` — clean. - Manual: `curl -s https://<instance>/api/health` as an anonymous caller returns `"commit": "<full sha>"` alongside the existing redacted fields. ## Risks - **Version disclosure:** anonymous callers can now fingerprint the exact running commit. This is a deliberate trade-off: the builds are of a public repository (the SHA reveals no private code), the endpoint already responds to anonymous callers, and the operational value — verifying deploys actually shipped — outweighs the marginal fingerprinting surface. Operators who consider this sensitive are typically fronting `/api` with their own access controls already. - Otherwise low risk: no behavioral change to any gated field, no schema or API-surface removal; `commit: null` keeps the field shape stable when git metadata is absent (e.g. non-git installs). ## Model Used Claude Opus 4.8 (`claude-opus-4-8`, extended thinking, via Claude Code with tool use and code execution) authored the change and tests; finalized and PR'd under Claude Fable 5 (`claude-fable-5`). ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes (none needed beyond code comments — health endpoint has no standalone doc) - [x] I have considered and documented any risks above - [x] All Paperclip CI gates are green - [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge
This commit is contained in:
Devin Foley
GitHub
parent
d295251550
commit
51bb41c7e3
|
|
@ -85,6 +85,12 @@ describe("GET /health dev-server supervisor access", () => {
|
|||
deploymentExposure: "private",
|
||||
authReady: true,
|
||||
companyDeletionEnabled: true,
|
||||
// Pin server info so the commit field is deterministic (null)
|
||||
// instead of picking up the checkout's real git metadata.
|
||||
serverInfo: {
|
||||
processStartedAt: "2026-03-20T11:00:00.000Z",
|
||||
git: { available: false, unavailableReason: "git_unavailable" },
|
||||
},
|
||||
}),
|
||||
);
|
||||
|
||||
|
|
@ -97,6 +103,7 @@ describe("GET /health dev-server supervisor access", () => {
|
|||
status: "ok",
|
||||
deploymentMode: "authenticated",
|
||||
deploymentExposure: "private",
|
||||
commit: null,
|
||||
bootstrapStatus: "ready",
|
||||
bootstrapInviteActive: false,
|
||||
devServer: {
|
||||
|
|
|
|||
|
|
@ -74,7 +74,7 @@ describe("GET /health", () => {
|
|||
const app = createApp();
|
||||
const res = await request(app).get("/health");
|
||||
expect(res.status).toBe(200);
|
||||
expect(res.body).toEqual({ status: "ok", version: serverVersion, serverVersion: serverVersion, serverInfo: testServerInfo });
|
||||
expect(res.body).toEqual({ status: "ok", version: serverVersion, serverVersion: serverVersion, commit: testServerInfo.git.fullSha, serverInfo: testServerInfo });
|
||||
}, 15_000);
|
||||
|
||||
it("returns 200 when the database probe succeeds", async () => {
|
||||
|
|
@ -107,6 +107,7 @@ describe("GET /health", () => {
|
|||
status: "unhealthy",
|
||||
version: serverVersion,
|
||||
serverVersion,
|
||||
commit: testServerInfo.git.fullSha,
|
||||
error: "database_unreachable",
|
||||
serverInfo: testServerInfo,
|
||||
});
|
||||
|
|
@ -131,6 +132,8 @@ describe("GET /health", () => {
|
|||
unavailableReason: "git_unavailable",
|
||||
},
|
||||
});
|
||||
// With no git metadata baked in, the exposed commit is null (not omitted).
|
||||
expect(res.body.commit).toBeNull();
|
||||
});
|
||||
|
||||
it("surfaces a stale database backup warning in full health details", async () => {
|
||||
|
|
@ -281,6 +284,7 @@ describe("GET /health", () => {
|
|||
status: "ok",
|
||||
deploymentMode: "authenticated",
|
||||
deploymentExposure: "public",
|
||||
commit: testServerInfo.git.fullSha,
|
||||
bootstrapStatus: "ready",
|
||||
bootstrapInviteActive: false,
|
||||
databaseBackup: {
|
||||
|
|
@ -337,6 +341,7 @@ describe("GET /health", () => {
|
|||
status: "ok",
|
||||
deploymentMode: "authenticated",
|
||||
deploymentExposure: "public",
|
||||
commit: testServerInfo.git.fullSha,
|
||||
bootstrapStatus: "ready",
|
||||
bootstrapInviteActive: false,
|
||||
});
|
||||
|
|
@ -374,6 +379,7 @@ describe("GET /health", () => {
|
|||
status: "ok",
|
||||
deploymentMode: "authenticated",
|
||||
deploymentExposure: "public",
|
||||
commit: testServerInfo.git.fullSha,
|
||||
bootstrapStatus: "ready",
|
||||
bootstrapInviteActive: false,
|
||||
});
|
||||
|
|
|
|||
|
|
@ -121,14 +121,19 @@ export function healthRoutes(
|
|||
// enableServerInfoDebugView experimental flag gates the UI surface, not this
|
||||
// already access-controlled field.
|
||||
const serverInfo = opts.serverInfo ?? getServerInfoSnapshot();
|
||||
// The build commit is a plain git SHA of a public repository — not a
|
||||
// secret — so it is surfaced on every response, including the redacted
|
||||
// one, unlike the fuller `serverInfo` block. Deploy tooling (and anyone)
|
||||
// can read which commit this server is running without authenticating.
|
||||
const commit = serverInfo.git.available ? serverInfo.git.fullSha : null;
|
||||
const exposeDevServerDetails =
|
||||
exposeFullDetails || hasDevServerStatusToken(req.get("x-paperclip-dev-server-status-token"));
|
||||
|
||||
if (!db) {
|
||||
res.json(
|
||||
exposeFullDetails
|
||||
? { status: "ok", version: serverVersion, serverVersion: serverVersion, serverInfo }
|
||||
: { status: "ok", deploymentMode: opts.deploymentMode },
|
||||
? { status: "ok", version: serverVersion, serverVersion: serverVersion, commit, serverInfo }
|
||||
: { status: "ok", deploymentMode: opts.deploymentMode, commit },
|
||||
);
|
||||
return;
|
||||
}
|
||||
|
|
@ -141,6 +146,7 @@ export function healthRoutes(
|
|||
status: "unhealthy",
|
||||
version: serverVersion,
|
||||
serverVersion,
|
||||
commit,
|
||||
error: "database_unreachable",
|
||||
...(exposeFullDetails ? { serverInfo } : {}),
|
||||
});
|
||||
|
|
@ -210,6 +216,7 @@ export function healthRoutes(
|
|||
status: "ok",
|
||||
deploymentMode: opts.deploymentMode,
|
||||
deploymentExposure: opts.deploymentExposure,
|
||||
commit,
|
||||
bootstrapStatus,
|
||||
bootstrapInviteActive,
|
||||
...(redactedDatabaseBackup ? { databaseBackup: redactedDatabaseBackup } : {}),
|
||||
|
|
@ -223,6 +230,7 @@ export function healthRoutes(
|
|||
status: "ok",
|
||||
version: serverVersion,
|
||||
serverVersion,
|
||||
commit,
|
||||
deploymentMode: opts.deploymentMode,
|
||||
deploymentExposure: opts.deploymentExposure,
|
||||
authReady: opts.authReady,
|
||||
|
|
|
|||
|
|
@ -1054,6 +1054,39 @@ function applyDocumentFixups(document: any): any {
|
|||
|
||||
// ─── Health ──────────────────────────────────────────────────────────────────
|
||||
|
||||
// Shared by the healthy and database-unreachable responses: full details
|
||||
// (including serverInfo) ride only on board/agent-actor responses.
|
||||
const healthServerInfoSchema = z.object({
|
||||
processStartedAt: z.string().datetime(),
|
||||
git: z.union([
|
||||
z.object({
|
||||
available: z.literal(true),
|
||||
fullSha: z.string(),
|
||||
shortSha: z.string(),
|
||||
branchName: z.string().nullable(),
|
||||
subject: z.string(),
|
||||
committedAt: z.string().datetime().nullable(),
|
||||
localChanges: z.union([
|
||||
z.object({
|
||||
available: z.literal(true),
|
||||
hasLocalChanges: z.boolean(),
|
||||
stagedFileCount: z.number().int().nonnegative(),
|
||||
unstagedFileCount: z.number().int().nonnegative(),
|
||||
untrackedFileCount: z.number().int().nonnegative(),
|
||||
}).strict(),
|
||||
z.object({
|
||||
available: z.literal(false),
|
||||
unavailableReason: z.enum(["git_status_unavailable"]),
|
||||
}).strict(),
|
||||
]),
|
||||
}).strict(),
|
||||
z.object({
|
||||
available: z.literal(false),
|
||||
unavailableReason: z.enum(["git_unavailable", "invalid_git_metadata"]),
|
||||
}).strict(),
|
||||
]),
|
||||
}).strict();
|
||||
|
||||
registry.registerPath({
|
||||
method: "get",
|
||||
path: "/api/health",
|
||||
|
|
@ -1063,6 +1096,9 @@ registry.registerPath({
|
|||
200: r.ok(z.object({
|
||||
status: z.enum(["ok", "unhealthy"]),
|
||||
version: z.string().optional(),
|
||||
// Running build commit (full git SHA), or null when git metadata is
|
||||
// unavailable. Present on every response shape, including redacted ones.
|
||||
commit: z.string().nullable(),
|
||||
deploymentMode: z.string().optional(),
|
||||
bootstrapStatus: z.enum(["ready", "bootstrap_pending"]).optional(),
|
||||
bootstrapInviteActive: z.boolean().optional(),
|
||||
|
|
@ -1097,38 +1133,26 @@ registry.registerPath({
|
|||
code: z.string(),
|
||||
message: z.string(),
|
||||
})).optional(),
|
||||
serverInfo: z.object({
|
||||
processStartedAt: z.string().datetime(),
|
||||
git: z.union([
|
||||
z.object({
|
||||
available: z.literal(true),
|
||||
fullSha: z.string(),
|
||||
shortSha: z.string(),
|
||||
branchName: z.string().nullable(),
|
||||
subject: z.string(),
|
||||
committedAt: z.string().datetime().nullable(),
|
||||
localChanges: z.union([
|
||||
z.object({
|
||||
available: z.literal(true),
|
||||
hasLocalChanges: z.boolean(),
|
||||
stagedFileCount: z.number().int().nonnegative(),
|
||||
unstagedFileCount: z.number().int().nonnegative(),
|
||||
untrackedFileCount: z.number().int().nonnegative(),
|
||||
}).strict(),
|
||||
z.object({
|
||||
available: z.literal(false),
|
||||
unavailableReason: z.enum(["git_status_unavailable"]),
|
||||
}).strict(),
|
||||
]),
|
||||
}).strict(),
|
||||
z.object({
|
||||
available: z.literal(false),
|
||||
unavailableReason: z.enum(["git_unavailable", "invalid_git_metadata"]),
|
||||
}).strict(),
|
||||
]),
|
||||
}).strict().optional(),
|
||||
serverInfo: healthServerInfoSchema.optional(),
|
||||
})),
|
||||
503: { description: "Service unavailable", content: { "application/json": { schema: ErrorSchema } } },
|
||||
// The database-unreachable body still carries version and commit so
|
||||
// deployment tooling can verify the running build during an outage;
|
||||
// serverInfo rides only on full-details (board/agent) responses.
|
||||
503: {
|
||||
description: "Service unavailable",
|
||||
content: {
|
||||
"application/json": {
|
||||
schema: z.object({
|
||||
status: z.literal("unhealthy"),
|
||||
version: z.string(),
|
||||
serverVersion: z.string(),
|
||||
commit: z.string().nullable(),
|
||||
error: z.literal("database_unreachable"),
|
||||
serverInfo: healthServerInfoSchema.optional(),
|
||||
}),
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
});
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue