docs: sign the commits you push, and say so at install (#1836)

Author: FelixTJDietrich

CONTRIBUTING.md

@@ -24,6 +24,26 @@ To ensure a transparent and trustworthy environment, we have established differe
 2. **Forking**: Fork the repository and work on changes in your own branch.
 3. **Pull Request**: Submit a PR from your fork. Ensure your branch is up to date with `main`.
 
+### Signed Commits
+
+A commit pushed to a branch in this repository is signed, and its commit email is an address verified on your GitHub account; a push carrying an unsigned commit is refused. A pull request from a fork needs none of this — the commit that lands on `main` is created and signed by GitHub.
+
+Sign with the SSH key you already push with — [GitHub accepts an authentication key a second time as a signing key](https://docs.github.com/en/authentication/managing-commit-signature-verification/about-commit-signature-verification):
+
+```bash
+git config --global gpg.format ssh
+git config --global user.signingkey ~/.ssh/id_ed25519.pub
+git config --global commit.gpgsign true
+```
+
+Then register that public key on GitHub under Settings → SSH and GPG keys → New SSH key with the key type **Signing Key**, or run `gh ssh-key add ~/.ssh/id_ed25519.pub --type signing`. Until it is registered as a signing key, signatures made with it stay unverified. `vp install` warns when this is not configured.
+
+If a push is refused, sign the commits your branch already carries and force-push:
+
+```bash
+git rebase --exec 'git commit --amend --no-edit -S' origin/main
+```
+
 ### Compliance
 
 Every commit on a pull request must be authored by an email address that resolves to the GitHub account that opened it, so set `git config user.email` accordingly before you commit.

docs/contributor/local-development.mdx

@@ -34,6 +34,8 @@ Install and configure the following tools before you attempt a local build:
    After `vp install`, `vp --version` prints the pinned `vite-plus`.
 4. **NATS CLI (optional)** – Helpful when inspecting the webhook/sync event stream (NATS is disabled by default locally). The agent job queue runs on PostgreSQL and needs no NATS.
 
+If you push branches to the repository rather than to a fork, configure commit signing as well — [CONTRIBUTING.md § Signed Commits](https://github.com/hephaestus-build/Hephaestus/blob/main/CONTRIBUTING.md#signed-commits) has the setup, and `vp install` warns while it is missing.
+
 ## Recommended IDE setup
 
 Open the repository using the `project.code-workspace` file in VS Code and install the workspace recommendations (`@recommended` in the Extensions view). Key extensions include:

scripts/enable-hooks.test.ts

@@ -1,6 +1,6 @@
 import assert from "node:assert/strict";
 import { execFileSync, spawnSync } from "node:child_process";
-import { cpSync, mkdtempSync, rmSync } from "node:fs";
+import { cpSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join, resolve } from "node:path";
 import { after, test } from "node:test";
@@ -9,25 +9,42 @@ import { CAPTURE_LIMIT_BYTES } from "./lib/process.ts";
 
 const REPO_ROOT = resolve(import.meta.dirname, "..");
 const SCRIPT = join(REPO_ROOT, "scripts", "enable-hooks.ts");
-const repositories: string[] = [];
+const temporaries: string[] = [];
+
+/** A global Git config holding exactly these lines, so the machine's own cannot decide a test. */
+function globalConfig(contents = ""): string {
+	const directory = mkdtempSync(join(tmpdir(), "enable-hooks-config-"));
+	temporaries.push(directory);
+	const path = join(directory, "gitconfig");
+	writeFileSync(path, contents);
+	return path;
+}
+
+const EMPTY_GLOBAL_CONFIG = globalConfig();
 
 /**
  * Git exports `GIT_DIR` and its siblings to every hook process, and they outrank a child's `cwd`.
  * Inherited, they would point both the script under test and the assertions at the repository the
- * hook is running in rather than at the clone made below.
+ * hook is running in rather than at the clone made below. The global and system configs are then
+ * replaced rather than dropped, because what a developer's own config says about commit signing is
+ * exactly what these tests decide.
  */
-function hookFreeEnv(): NodeJS.ProcessEnv {
-	return Object.fromEntries(Object.entries(process.env).filter(([key]) => !key.startsWith("GIT_")));
+function hookFreeEnv(configPath: string = EMPTY_GLOBAL_CONFIG): NodeJS.ProcessEnv {
+	return {
+		...Object.fromEntries(Object.entries(process.env).filter(([key]) => !key.startsWith("GIT_"))),
+		GIT_CONFIG_GLOBAL: configPath,
+		GIT_CONFIG_NOSYSTEM: "1",
+	};
 }
 
 after(() => {
-	for (const repository of repositories) rmSync(repository, { recursive: true, force: true });
+	for (const temporary of temporaries) rmSync(temporary, { recursive: true, force: true });
 });
 
 /** A clone with the project hooks whose Git still points at an earlier hook manager's directory. */
 function clone(): { repository: string; git: (...args: string[]) => string } {
 	const repository = mkdtempSync(join(tmpdir(), "enable-hooks-"));
-	repositories.push(repository);
+	temporaries.push(repository);
 	const git = (...args: string[]): string =>
 		execFileSync("git", args, {
 			cwd: repository,
@@ -80,3 +97,31 @@ void test("an install under a hook's GIT_DIR configures the clone it runs in", (
 	assert.equal(git("config", "core.hooksPath"), ".vite-hooks/_");
 	assert.equal(decoy.git("config", "core.hooksPath"), ".husky/_");
 });
+
+void test("an install without commit signing configured warns and still succeeds", () => {
+	const { repository } = clone();
+	const result = spawnSync("node", [SCRIPT], {
+		cwd: repository,
+		encoding: "utf8",
+		maxBuffer: CAPTURE_LIMIT_BYTES,
+		env: hookFreeEnv(),
+	});
+	assert.equal(result.status, 0, `${result.stdout}${result.stderr}`);
+	assert.match(result.stderr, /git config --global commit\.gpgsign true/);
+	assert.match(result.stderr, /gh ssh-key add .* --type signing/);
+});
+
+void test("an install with commit signing configured says nothing about it", () => {
+	const { repository } = clone();
+	const signing = globalConfig(
+		"[gpg]\n\tformat = ssh\n[user]\n\tsigningkey = ~/.ssh/id_ed25519.pub\n[commit]\n\tgpgsign = true\n",
+	);
+	const result = spawnSync("node", [SCRIPT], {
+		cwd: repository,
+		encoding: "utf8",
+		maxBuffer: CAPTURE_LIMIT_BYTES,
+		env: hookFreeEnv(signing),
+	});
+	assert.equal(result.status, 0, `${result.stdout}${result.stderr}`);
+	assert.doesNotMatch(result.stderr, /commit\.gpgsign/);
+});

scripts/enable-hooks.ts

@@ -10,6 +10,25 @@ import { CAPTURE_LIMIT_BYTES } from "./lib/process.ts";
 
 const HOOKS_DIR = ".vite-hooks";
 
+/**
+ * The repository refuses a push whose commits are unsigned, and an install is the last moment a
+ * contributor is in front of the machine that has to sign. It is a warning rather than a failure:
+ * a clone with no signing key still has to be able to build.
+ */
+const SIGNING_WARNING = `
+warning: commits pushed to a branch in this repository must be signed, and this checkout is not
+configured to sign. Sign with the SSH key you already push with:
+
+  git config --global gpg.format ssh
+  git config --global user.signingkey ~/.ssh/id_ed25519.pub
+  git config --global commit.gpgsign true
+
+Then register that public key on GitHub as a signing key — Settings > SSH and GPG keys > New SSH
+key, key type "Signing Key", or: gh ssh-key add ~/.ssh/id_ed25519.pub --type signing
+
+CONTRIBUTING.md, under "Signed Commits", has the rest.
+`;
+
 function git(...args: string[]): string {
 	try {
 		return execFileSync("git", args, {
@@ -31,4 +50,10 @@ if (git("rev-parse", "--is-inside-work-tree") === "true") {
 		stdio: "inherit",
 	});
 	process.exitCode = enabled.status ?? 1;
+
+	// `--type=bool` so `1`, `yes` and `on` count as configured; every `gpg.format` signs.
+	const signs =
+		git("config", "--get", "--type=bool", "commit.gpgsign") === "true" &&
+		git("config", "--get", "user.signingkey") !== "";
+	if (!signs) process.stderr.write(SIGNING_WARNING);
 }

scripts/plan-release.test.ts

@@ -147,13 +147,23 @@ after(() => {
 void test("reads schema migrations from the diff between the two releases", async () => {
 	const repo = mkdtempSync(join(tmpdir(), "plan-release-"));
 	repositories.push(repo);
+	// A developer's own `tag.gpgSign` would turn the lightweight tag below into an annotated one and
+	// send git looking for an editor, so the fixture reads an empty global config instead.
+	const configDirectory = mkdtempSync(join(tmpdir(), "plan-release-config-"));
+	repositories.push(configDirectory);
+	const globalConfig = join(configDirectory, "gitconfig");
+	writeFileSync(globalConfig, "");
 	const git = (...args: string[]): string =>
 		execFileSync("git", args, {
 			cwd: repo,
 			encoding: "utf8",
-			env: Object.fromEntries(
-				Object.entries(process.env).filter(([key]) => !key.startsWith("GIT_")),
-			),
+			env: {
+				...Object.fromEntries(
+					Object.entries(process.env).filter(([key]) => !key.startsWith("GIT_")),
+				),
+				GIT_CONFIG_GLOBAL: globalConfig,
+				GIT_CONFIG_NOSYSTEM: "1",
+			},
 			stdio: ["ignore", "pipe", "pipe"],
 		}).trim();
 	const changelog = "server/application/src/main/resources/db/changelog";