fix(deps): automate reproducible supply-chain updates

Author: FelixTJDietrich

.changeset/bright-supply-chain.md

@@ -0,0 +1,5 @@
+---
+"hephaestus": patch
+---
+
+Makes the agent and PostgreSQL images reproducible by installing the agent SDK from a committed lockfile and pinning every supported PostgreSQL base image by digest.

docker/agents/pi/Dockerfile

@@ -1,7 +1,15 @@
 # syntax=docker/dockerfile:1.26@sha256:ecfaec9ed6d810b56388c508f4121597bfbba70d41a6dfeee4d8cad5f295fc32
 # renovate: datasource=docker depName=node
 ARG NODE_VERSION=24.19.0
+FROM ghcr.io/pnpm/pnpm:12.0.0@sha256:bce5ae25ef95edd79e696d7fa8489b80561ef660100fd35bd0286d0f90db3dcc AS dependencies
+ARG NODE_VERSION
+WORKDIR /opt/pi-sdk
+RUN pnpm runtime set node ${NODE_VERSION} -g
+COPY pi/package.json pi/pnpm-lock.yaml ./
+RUN pnpm install --prod --frozen-lockfile --ignore-scripts --ignore-workspace
+
 FROM node:${NODE_VERSION}-slim@sha256:a9f5f7c91a432850b2a8a7797adf5eadb6c733ceed61167806cee7ea7fbc29df
+ARG NODE_VERSION
 
 # The base digest is pinned, so Debian security updates published after the upstream image was
 # built can reach it only here; Renovate bumps the digest only when upstream republishes one.
@@ -22,13 +30,9 @@ RUN groupmod --new-name agent node && \
 
 # renovate: datasource=npm depName=@earendil-works/pi-coding-agent
 ARG PI_VERSION=0.84.3
-RUN mkdir -p /opt/pi-sdk && cd /opt/pi-sdk && \
-    printf '{"name":"hephaestus-pi-sdk","private":true,"dependencies":{"@earendil-works/pi-coding-agent":"%s"}}\n' \
-        "${PI_VERSION}" > package.json && \
-    npm install --omit=dev --ignore-scripts --no-audit --no-fund && \
-    test -d /opt/pi-sdk/node_modules/@earendil-works/pi-coding-agent \
+COPY --from=dependencies --chown=1000:1000 /opt/pi-sdk /opt/pi-sdk
+RUN test -d /opt/pi-sdk/node_modules/@earendil-works/pi-coding-agent \
       || (echo "Pi SDK not found at /opt/pi-sdk/node_modules" >&2; exit 1) && \
-    chown -R 1000:1000 /opt/pi-sdk && \
     mkdir -p /workspace && chown 1000:1000 /workspace
 
 RUN mkdir -p /tmp/abi-check && ln -sf /opt/pi-sdk/node_modules /tmp/abi-check/node_modules && \

docker/agents/pi/package.json

@@ -0,0 +1,8 @@
+{
+  "name": "hephaestus-pi-sdk",
+  "private": true,
+  "version": "0.0.0",
+  "dependencies": {
+    "@earendil-works/pi-coding-agent": "0.84.3"
+  }
+}

docker/agents/pi/pnpm-lock.yaml

@@ -2,7 +2,9 @@
 # environment (Alpine has no partman package). No shared_preload_libraries: maintenance runs as plain
 # SQL from the app scheduler, so this stays stock Postgres + one extension. See ADR 0018 and ADR 0038.
 ARG PG_MAJOR=18
-FROM postgres:${PG_MAJOR}-bookworm
+FROM postgres:18-bookworm@sha256:1c59e2c3c818eaa0f0628f695b36e7c9e362d6b219b36a54a32df645cbd7e1af AS postgres-18
+FROM postgres:17-bookworm@sha256:051f7b7b3abdd564d5d1bd1e8c4b9c1b6e77087d1dd22020ede611c096a272e0 AS postgres-17
+FROM postgres-${PG_MAJOR}
 ARG PG_MAJOR=18
 # Pinned for reproducibility (PGDG bookworm pool). Bump deliberately.
 ARG PARTMAN_VERSION=5.5.0-1.pgdg12+1

docker/postgres/Dockerfile

@@ -98,6 +98,18 @@ source validation.
 | OpenSSF Scorecard | `main`, branch-protection changes, and weekly | posture findings do not extend the pull-request critical path | code scanning and run artifact |
 | Renovate | configured schedule and vulnerability alerts | pull requests require normal review and CI | dependency dashboard |
 
+Renovate opens bounded, independently reviewable update pull requests on weekday mornings; only
+major updates wait for an explicit Dependency Dashboard approval. Vulnerability alerts bypass the
+normal release-age delay and approval gate. Native managers cover package manifests, lockfiles,
+container bases, Maven, and GitHub Actions, while tested regex managers cover version declarations
+that have no native manager. The dashboard is an inventory and decision surface, not a queue that
+maintainers must drain before routine fixes can start.
+
+Renovate is not the supply-chain inventory by itself: it discovers update coordinates in source,
+whereas lockfiles describe resolved package graphs and release SBOMs describe the contents of final
+artifacts. Dependency review, image scanning, signed provenance, scheduled rescans, and the release
+SBOM therefore remain required layers rather than substitutes for dependency updates.
+
 [Vulnerability remediation](./vulnerability-remediation.mdx) owns the blocking and exception policy.
 [Release management](./release-management.mdx#supply-chain-evidence) owns artifact signing, provenance,
 SBOM, and release-verification guarantees.

docs/contributor/ci-cd.mdx

@@ -1,14 +1,10 @@
 {
 	"$schema": "https://docs.renovatebot.com/renovate-schema.json",
-	"extends": [
-		"config:best-practices",
-		":semanticCommitTypeAll(chore)",
-		":dependencyDashboardApproval"
-	],
+	"extends": ["config:best-practices", ":semanticCommitTypeAll(chore)"],
 	"labels": ["dependencies"],
 	"assigneesFromCodeOwners": true,
 	"timezone": "Europe/Berlin",
-	"schedule": ["before 7am on monday"],
+	"schedule": ["before 7am every weekday"],
 	"minimumReleaseAge": "3 days",
 	"semanticCommitScope": "deps",
 	"enabledManagers": [
@@ -37,48 +33,43 @@
 			"matchManagers": ["maven"],
 			"matchDepTypes": ["compile", "runtime", "provided", "optional", "parent", "parent-root"],
 			"matchUpdateTypes": ["minor", "patch", "digest", "pin", "pinDigest"],
-			"groupName": "Java runtime and framework dependencies",
 			"labels": ["dependencies", "java"]
 		},
 		{
 			"matchManagers": ["maven"],
 			"matchDepTypes": ["build", "test"],
 			"matchUpdateTypes": ["minor", "patch", "digest", "pin", "pinDigest"],
-			"groupName": "Java developer tooling",
 			"labels": ["dependencies", "java"]
 		},
 		{
 			"matchFileNames": ["webapp/package.json"],
 			"matchDepTypes": ["dependencies"],
 			"matchUpdateTypes": ["minor", "patch"],
-			"groupName": "Webapp runtime dependencies",
 			"labels": ["dependencies", "webapp"]
 		},
 		{
 			"matchFileNames": ["webapp/package.json"],
 			"matchDepTypes": ["devDependencies"],
 			"matchUpdateTypes": ["minor", "patch"],
-			"groupName": "Webapp developer tooling",
 			"labels": ["dependencies", "webapp"]
 		},
 		{
 			"matchFileNames": ["docs/package.json"],
 			"matchDepTypes": ["dependencies"],
 			"matchUpdateTypes": ["minor", "patch"],
-			"groupName": "Documentation runtime dependencies",
 			"labels": ["dependencies", "docs"]
 		},
 		{
 			"matchFileNames": ["docs/package.json"],
 			"matchDepTypes": ["devDependencies"],
 			"matchUpdateTypes": ["minor", "patch"],
-			"groupName": "Documentation developer tooling",
 			"labels": ["dependencies", "docs"]
 		},
 		{
 			"matchUpdateTypes": ["major"],
 			"minimumReleaseAge": "7 days",
-			"labels": ["dependencies", "breaking"]
+			"labels": ["dependencies", "breaking"],
+			"dependencyDashboardApproval": true
 		},
 		{
 			"matchPackageNames": [
@@ -88,8 +79,7 @@
 				"/^@tanstack/",
 				"/^org\\.springframework/"
 			],
-			"matchUpdateTypes": ["minor"],
-			"groupName": "Core frameworks"
+			"matchUpdateTypes": ["minor"]
 		},
 		{
 			"matchManagers": ["github-actions"],
@@ -103,7 +93,8 @@
 		},
 		{
 			"matchUpdateTypes": ["major"],
-			"groupName": null
+			"groupName": null,
+			"dependencyDashboardApproval": true
 		}
 	],
 	"customManagers": [
@@ -135,6 +126,16 @@
 			],
 			"versioningTemplate": "semver"
 		},
+		{
+			"description": "Track the OpenAPI Generator CLI distribution",
+			"customType": "regex",
+			"managerFilePatterns": ["/^openapitools\\.json$/"],
+			"matchStrings": ["\"version\": \"(?<currentValue>[^\"]+)\""],
+			"datasourceTemplate": "github-releases",
+			"depNameTemplate": "OpenAPITools/openapi-generator",
+			"extractVersionTemplate": "^v(?<version>.*)$",
+			"versioningTemplate": "semver"
+		},
 		{
 			"description": "Track release image tags and digests",
 			"customType": "regex",
@@ -153,5 +154,10 @@
 		"automerge": false,
 		"groupName": null
 	},
-	"ignorePaths": ["**/node_modules/**", "**/target/**", "**/dist/**", "**/build/**"]
+	"ignorePaths": ["**/node_modules/**", "**/target/**", "**/dist/**", "**/build/**"],
+	"prConcurrentLimit": 5,
+	"branchConcurrentLimit": 10,
+	"prHourlyLimit": 2,
+	"osvVulnerabilityAlerts": true,
+	"dependencyDashboardOSVVulnerabilitySummary": "unresolved"
 }

renovate.json

@@ -1,9 +1,16 @@
 import { readFileSync } from "node:fs";
 
+import { parse } from "yaml";
+
 import { asRecord, isRecord, parseJson } from "./lib/json.ts";
 
 const dockerfile = readFileSync("docker/agents/pi/Dockerfile", "utf8");
+const webappDockerfile = readFileSync("webapp/Dockerfile", "utf8");
 const packageJson = asRecord(parseJson(readFileSync("package.json", "utf8")), "package.json");
+const imagePackageJson = asRecord(
+	parseJson(readFileSync("docker/agents/pi/package.json", "utf8")),
+	"docker/agents/pi/package.json",
+);
 const devDependencies = isRecord(packageJson.devDependencies) ? packageJson.devDependencies : {};
 const problems: string[] = [];
 
@@ -26,12 +33,42 @@ if (repoNodeVersion !== nodeVersion) {
 		`package.json#devEngines.runtime pins Node ${String(repoNodeVersion)} but the agent image pins ${nodeVersion}.`,
 	);
 }
+const webappNodeVersion = /^ARG NODE_VERSION=(\S+)$/m.exec(webappDockerfile)?.[1];
+if (webappNodeVersion !== nodeVersion) {
+	problems.push(
+		`webapp/Dockerfile pins Node ${String(webappNodeVersion)} but the agent image pins ${nodeVersion}.`,
+	);
+}
 const packagePiVersion = devDependencies["@earendil-works/pi-coding-agent"];
 if (packagePiVersion !== piVersion) {
 	problems.push(
 		`package.json pins Pi ${String(packagePiVersion)} but the agent image pins ${piVersion}.`,
 	);
 }
+const imageDependencies = isRecord(imagePackageJson.dependencies)
+	? imagePackageJson.dependencies
+	: {};
+if (imageDependencies["@earendil-works/pi-coding-agent"] !== piVersion) {
+	problems.push(
+		`docker/agents/pi/package.json pins Pi ${String(imageDependencies["@earendil-works/pi-coding-agent"])} but the agent image pins ${piVersion}.`,
+	);
+}
+
+const imageLock = asRecord(
+	parse(readFileSync("docker/agents/pi/pnpm-lock.yaml", "utf8")),
+	"docker/agents/pi/pnpm-lock.yaml",
+);
+const lockImporters = isRecord(imageLock.importers) ? imageLock.importers : {};
+const lockRoot = isRecord(lockImporters["."]) ? lockImporters["."] : {};
+const lockDependencies = isRecord(lockRoot.dependencies) ? lockRoot.dependencies : {};
+const lockedPi = isRecord(lockDependencies["@earendil-works/pi-coding-agent"])
+	? lockDependencies["@earendil-works/pi-coding-agent"]
+	: {};
+if (lockedPi.specifier !== piVersion || !String(lockedPi.version).startsWith(`${piVersion}(`)) {
+	problems.push(
+		`docker/agents/pi/pnpm-lock.yaml does not resolve the image's Pi ${piVersion} dependency.`,
+	);
+}
 
 const javaPin = /private static final String PI_SDK_VERSION = "([^"]+)";/;
 for (const path of [

scripts/check-agent-runtime-pins.ts

@@ -137,7 +137,10 @@ const dockerfile = readFileSync("webapp/Dockerfile", "utf8");
 if (!dockerfile.includes(`ghcr.io/pnpm/pnpm:${version}@sha256:`)) {
 	throw new Error(`webapp/Dockerfile must use the digest-pinned pnpm ${version} image`);
 }
-if (!dockerfile.includes(`pnpm runtime set node ${runtime.version} -g`)) {
+if (
+	!dockerfile.includes(`ARG NODE_VERSION=${runtime.version}`) ||
+	!dockerfile.includes(["pnpm runtime set node $", "{NODE_VERSION} -g"].join(""))
+) {
 	throw new Error(`webapp/Dockerfile must install Node ${runtime.version} through pnpm`);
 }
 

scripts/check-package-manager.ts

@@ -0,0 +1,78 @@
+import assert from "node:assert/strict";
+import { readFile } from "node:fs/promises";
+import { test } from "node:test";
+
+import { isRecord, parseJson } from "./lib/json.ts";
+
+const parsedConfig: unknown = parseJson(await readFile("renovate.json", "utf8"));
+assert.ok(isRecord(parsedConfig));
+const config = parsedConfig;
+assert.ok(Array.isArray(config.extends));
+assert.ok(config.extends.every((entry) => typeof entry === "string"));
+const extensions = config.extends;
+
+void test("Renovate creates bounded update PRs without a manual dispatch queue", () => {
+	assert.ok(extensions.includes("config:best-practices"));
+	assert.ok(!extensions.includes(":dependencyDashboardApproval"));
+	assert.deepEqual(config.schedule, ["before 7am every weekday"]);
+	assert.equal(config.prHourlyLimit, 2);
+	assert.equal(config.prConcurrentLimit, 5);
+	assert.equal(config.branchConcurrentLimit, 10);
+	assert.ok(
+		Array.isArray(config.packageRules) &&
+			config.packageRules.some(
+				(rule) =>
+					isRecord(rule) &&
+					rule.dependencyDashboardApproval === true &&
+					Array.isArray(rule.matchUpdateTypes) &&
+					rule.matchUpdateTypes.includes("major"),
+			),
+	);
+});
+
+void test("vulnerability remediation bypasses normal update latency", () => {
+	assert.equal(config.osvVulnerabilityAlerts, true);
+	assert.equal(config.dependencyDashboardOSVVulnerabilitySummary, "unresolved");
+	assert.deepEqual(config.vulnerabilityAlerts, {
+		enabled: true,
+		minimumReleaseAge: null,
+		dependencyDashboardApproval: false,
+		automerge: false,
+		groupName: null,
+		labels: ["security", "dependencies"],
+	});
+});
+
+void test("every custom manager extracts a dependency from its real source", async () => {
+	const sources = new Map<string, string[]>([
+		["Track Dockerfile ARG version pins", ["docker/agents/pi/Dockerfile", "webapp/Dockerfile"]],
+		[
+			"Track release security tool versions",
+			[".github/actions/setup-release-security-tools/action.yml"],
+		],
+		["Track the Zizmor CLI version", [".github/workflows/cicd.yml"]],
+		["Track the OpenAPI Generator CLI distribution", ["openapitools.json"]],
+		["Track release image tags and digests", ["security/release-images.json"]],
+	]);
+	assert.ok(Array.isArray(config.customManagers));
+	assert.ok(config.customManagers.every(isRecord));
+	assert.deepEqual(
+		new Set(config.customManagers.map((manager) => manager.description)),
+		new Set(sources.keys()),
+	);
+	for (const manager of config.customManagers) {
+		if (typeof manager.description !== "string") throw new TypeError("manager description");
+		const description = manager.description;
+		assert.ok(Array.isArray(manager.matchStrings));
+		const files = sources.get(description);
+		assert.ok(files);
+		const contents = await Promise.all(files.map((file) => readFile(file, "utf8")));
+		for (const pattern of manager.matchStrings) {
+			if (typeof pattern !== "string") throw new TypeError("manager match pattern");
+			assert.ok(
+				contents.some((content) => new RegExp(pattern, "m").test(content)),
+				`${description} no longer matches its source`,
+			);
+		}
+	}
+});