@exadev/semantic-release-workspace 2.2.0 → 3.0.1

package/README.md

@@ -158,6 +158,7 @@ The core technique is the same one multi-semantic-release proved in production:
 - **Bump-only dependents always release.** multi-semantic-release rewrites dependency ranges in the working tree without committing them, so a dependent whose only change is a dependency update can go unreleased until some other commit triggers it. Here the bump is committed before the dependent's turn and a patch release is forced deterministically (see the timing section above).
 - **Loud failures by design.** A dependency cycle, an unsupported dependency range, a publish pipeline without @semantic-release/git (which would leave released manifests uncommitted), an unresolvable plugin, a duplicate package name — each stops the run with a specific error rather than degrading silently. There is deliberately no "skip this package and carry on" path: a partially-consistent set of publishes is worse than none.
 - **Only installable specifiers reach the registry.** `workspace:`, `catalog:`, `link:`, and `file:` specifiers in a publishable package's installed dependency fields are rejected instead of being published as written. In private packages and `devDependencies`, `workspace:*`/`workspace:^`/`workspace:~` are understood as naming no version (bump the release, not the manifest text), and `catalog:` and `npm:` aliases on a workspace sibling are rejected with an explanation instead of being mangled.
+- **Private packages release without advertising themselves.** A package marked `private` takes part in the run exactly as any other, tag and version bump and dependency cascade included, but creates no GitHub Release, because a Release for a package that never reaches a registry both points at nothing installable and takes the repository's Latest label off a package that does.
 - **Workspace-agnostic discovery.** Everything comes from `pnpm-workspace.yaml` and the manifests its globs match; pointing the orchestrator at any pnpm workspace is the entire configuration.
 
 Out of scope, on purpose: parallelising independent branches of the dependency graph (packages release sequentially in topological order for correctness first — a real future optimisation, not attempted here), and any Changesets-style explicit-changeset mode, which is a different paradigm rather than a missing feature.
@@ -225,11 +226,17 @@ Listing `@semantic-release/commit-analyzer` or `@semantic-release/release-notes-
 
 Note that the orchestrator sets `tagFormat`, `plugins`, `analyzeCommits`, and `generateNotes` explicitly on every per-package run, so those keys in any `release.config.*` found in the workspace are overridden by construction — configure the release through the orchestrator, not through a leftover single-package config.
 
-### Per-package publish plugins
+### Private packages and GitHub Releases
+
+A package whose manifest sets `"private": true` gets the workspace-wide plugin list minus `@semantic-release/github`, without being configured to. Nothing else about its release changes: it still gets its version bump, its `name@version` tag and the dependency cascade to its dependents, all of which a dependent's own release can hinge on (a private package whose build output ships inside a published one, for example). What it loses is a public GitHub Release for something nobody can install.
+
+That release is not merely redundant. `@semantic-release/github` sets the REST API's `make_latest` from the release branch alone, with no option to opt out, so every release it creates claims the repository's Latest label and the last one created keeps it. Topological order puts a package that depends on the published ones at the end of the run, which is exactly where a private package usually sits, so without this rule the repository's front page advertises an unpublishable package as its current release.
 
-`plugins` is one list for the whole workspace. `packagePlugins` (config file and programmatic API only, since a list keyed by package name has no natural flag form) replaces that list outright for the packages it names, and every other package keeps the workspace-wide list. The override is not merged with the workspace-wide list: it is the complete list for that package, subject to the same rules as any other (for instance `@semantic-release/git` is required under `commitStrategy: 'per-package'` and rejected under `'single'`). A name that is not a package in the workspace is rejected, so a misspelling cannot leave a package on the default list unnoticed.
+To keep the Release for a private package anyway, name it in `packagePlugins` below: an explicit list is taken exactly as written.
+
+### Per-package publish plugins
 
-The case this exists for is a private package. Such a package still needs its `name@version` tag, its version bump and the dependency cascade to its dependents, because a dependent's own release can hinge on it (a private package whose build output ships inside a published one, for example). It does not need a public GitHub Release, and `@semantic-release/github` marks every release it creates from the release branch as the repository's Latest, so GitHub ends up showing whichever package the run released last, which is often a private one that depends on the rest. Leaving that plugin off the private package's list removes the Release and nothing else:
+`plugins` is one list for the whole workspace. `packagePlugins` (config file and programmatic API only, since a list keyed by package name has no natural flag form) replaces that list outright for the packages it names, and every other package keeps the workspace-wide list, or the private-package variant of it described above. The override is not merged with either: it is the complete list for that package, subject to the same rules as any other (for instance `@semantic-release/git` is required under `commitStrategy: 'per-package'` and rejected under `'single'`). A name that is not a package in the workspace is rejected, so a misspelling cannot leave a package on the default list unnoticed.
 
 ```ts
 // release-workspace.config.ts
@@ -237,7 +244,10 @@ import { DEFAULT_PUBLISH_PLUGINS, type ReleaseWorkspaceOptions } from '@exadev/s
 
 const config: ReleaseWorkspaceOptions = {
   packagePlugins: {
-    '@acme/web-console': DEFAULT_PUBLISH_PLUGINS.filter((plugin) => plugin !== '@semantic-release/github'),
+    // A private package that does want its GitHub Release, opting back in to the list every public package gets.
+    '@acme/internal-tooling': DEFAULT_PUBLISH_PLUGINS,
+    // A published package kept out of a step the rest need.
+    '@acme/docs-site': DEFAULT_PUBLISH_PLUGINS.filter((plugin) => plugin !== '@semantic-release/npm'),
   },
 };
 

package/dist/cli.js

@@ -14,7 +14,7 @@ import { generateNotes } from "@semantic-release/release-notes-generator";
 import semanticRelease from "semantic-release";
 import { pathToFileURL } from "node:url";
 //#region package.json
-var version = "2.2.0";
+var version = "3.0.1";
 //#endregion
 //#region src/errors.ts
 /**
@@ -279,6 +279,53 @@ async function pushHeadAndTags(tagNames, options) {
 		...tagNames
 	], options);
 }
+/**
+* Fetches `branch` from origin and returns the commit it now points at.
+*
+* This is how a failed push is classified, in preference to reading the reason git printed for the rejection. The wording is not stable enough to branch on: the same race produces `! [rejected] ... (non-fast-forward)` from one server and `cannot lock ref 'refs/heads/main': is at <x> but expected <y>` from another (both observed, the first against GitHub and the second against a local bare repository under `--atomic`), and neither is a documented interface. Whether the branch actually moved is a fact about the remote rather than a string, it is the precise condition a retry can recover from, and it is knowable by asking.
+*/
+async function fetchBranchTip(branch, options) {
+	await git([
+		"fetch",
+		"origin",
+		branch
+	], options);
+	return (await git(["rev-parse", "FETCH_HEAD"], options)).trim();
+}
+/** Whether `ancestor` is reachable from `descendant`. `git merge-base --is-ancestor` reports the answer as an exit status rather than on stdout: 0 for yes and 1 for no are both answers, so only any other exit code is a failure. */
+async function isAncestor(ancestor, descendant, options) {
+	const args = [
+		"merge-base",
+		"--is-ancestor",
+		ancestor,
+		descendant
+	];
+	try {
+		await execGit(args, options.cwd);
+		return true;
+	} catch (cause) {
+		const error = toGitCommandError(args, options.cwd, cause);
+		if (error.exitCode === 1) return false;
+		throw error;
+	}
+}
+/** Discards every commit and working-tree change the current attempt made, putting the checkout back on exactly `ref`. */
+async function resetHardTo(ref, options) {
+	await git([
+		"reset",
+		"--hard",
+		ref
+	], options);
+}
+/** Deletes local tags. A retried attempt must drop the tags its predecessor created before it recreates them: `git tag` refuses a name that already exists, so without this the second attempt fails while tagging, before it ever reaches the push it was retrying. */
+async function deleteLocalTags(tagNames, options) {
+	if (tagNames.length === 0) return;
+	await git([
+		"tag",
+		"-d",
+		...tagNames
+	], options);
+}
 function toGitCommandError(args, cwd, cause) {
 	const exitCode = cause instanceof Error && "code" in cause && typeof cause.code === "number" ? cause.code : void 0;
 	const stderr = cause instanceof Error && "stderr" in cause && typeof cause.stderr === "string" ? cause.stderr.trim() : "";
@@ -602,6 +649,10 @@ function topologicalOrder(graph) {
 	if (pending.size > 0) throw new DependencyCycleError(findCycle(graph, new Set(pending.keys())));
 	return ordered;
 }
+/** The packages a release order names, in that order, for the stages that need each package's manifest rather than only its name. */
+function orderedPackages(graph, order) {
+	return order.map((name) => mustGet(graph.packages, name, "package"));
+}
 /**
 * Walks dependency edges between the packages Kahn's algorithm could not place, until it revisits one, so the error can name a concrete loop rather than just a set of packages. Every unplaced package is unplaced precisely because at least one of its own dependencies is too, so the walk always reaches a repeat.
 */
@@ -683,6 +734,8 @@ function matchTrailerLine(message, key) {
 }
 //#endregion
 //#region src/plugins.ts
+/** The one plugin a private package is kept off by default: see `resolveWorkspacePublishPlugins` for why a package that never reaches a registry does not get a public GitHub Release either. */
+const GITHUB_RELEASE_PLUGIN = "@semantic-release/github";
 /** semantic-release's own `getLastRelease` returns `{}` for a package with no prior tag -- not `undefined`, and not a fully-populated `LastRelease` -- contradicting the `gitHead: string` its own type declares. Narrows structurally rather than trusting that declared type, so a first-release context's `lastRelease` (correctly, at runtime) never claims a `gitHead` it does not have. */
 function hasGitHead(lastRelease) {
 	return typeof lastRelease === "object" && lastRelease !== null && "gitHead" in lastRelease && typeof lastRelease.gitHead === "string";
@@ -809,13 +862,17 @@ function resolvePublishPlugins(specs, workspaceRoot, options) {
 /**
 * Resolves the publish plugin list of every package in the workspace: the workspace-wide list for each package, except where `packagePlugins` names a package, whose own list replaces it. Every list is held to the same rules as `resolvePublishPlugins` applies to a workspace-wide one, and a failure in an override names the package it belongs to.
 *
+* A package whose manifest sets `private: true` and which no `packagePlugins` entry names gets the workspace-wide list minus `@semantic-release/github`. A private package is never published, so a public GitHub Release for it advertises something nobody can install, and that release is not merely redundant: `@semantic-release/github` sets `make_latest` from the release branch alone, with no option to opt out, so every release it creates claims the repository's Latest label and the last one created keeps it. A private package sitting at the end of the topological order (which is where a package that depends on the published ones necessarily sits) therefore takes the label on every run. Everything the private package actually needs from the run is untouched: its version bump, its tag, and the dependency cascade to its dependents all come from the other plugins and from the orchestrator itself.
+*
+* A `packagePlugins` entry naming a private package is taken exactly as written, `@semantic-release/github` included, so a workspace that does want a Release for a private package can still say so.
+*
 * A `packagePlugins` key that matches no package is rejected rather than ignored: a misspelt name would otherwise leave the package it meant on the workspace-wide list with nothing to say so, which for the intended use (keeping a package out of a step such as GitHub Release creation) is a silent wrong result.
 */
-function resolveWorkspacePublishPlugins(packageNames, specs, workspaceRoot, options) {
+function resolveWorkspacePublishPlugins(packages, specs, workspaceRoot, options) {
 	const overrides = specs.packagePlugins === void 0 ? [] : Object.entries(specs.packagePlugins);
-	const known = new Set(packageNames);
+	const known = new Set(packages.map((pkg) => pkg.name));
 	const unknown = overrides.map(([name]) => name).filter((name) => !known.has(name));
-	if (unknown.length > 0) throw new ReleaseConfigurationError(`packagePlugins names ${unknown.map((name) => `"${name}"`).join(", ")}, which ${unknown.length === 1 ? "is" : "are"} not a package in this workspace. Packages: ${packageNames.join(", ")}.`);
+	if (unknown.length > 0) throw new ReleaseConfigurationError(`packagePlugins names ${unknown.map((name) => `"${name}"`).join(", ")}, which ${unknown.length === 1 ? "is" : "are"} not a package in this workspace. Packages: ${[...known].join(", ")}.`);
 	const workspaceWide = resolvePublishPlugins(specs.plugins, workspaceRoot, options);
 	const resolvedOverrides = /* @__PURE__ */ new Map();
 	for (const [name, list] of overrides) try {
@@ -824,7 +881,9 @@ function resolveWorkspacePublishPlugins(packageNames, specs, workspaceRoot, opti
 		if (cause instanceof ReleaseConfigurationError) throw new ReleaseConfigurationError(`packagePlugins for "${name}": ${cause.message}`);
 		throw cause;
 	}
-	return new Map(packageNames.map((name) => [name, resolvedOverrides.get(name) ?? workspaceWide]));
+	const privateSpecs = specs.plugins.filter((spec) => parsePublishPluginSpec(spec)[0] !== GITHUB_RELEASE_PLUGIN);
+	const forPrivatePackages = privateSpecs.length === specs.plugins.length ? workspaceWide : resolvePublishPlugins(privateSpecs, workspaceRoot, options);
+	return new Map(packages.map((pkg) => [pkg.name, resolvedOverrides.get(pkg.name) ?? (pkg.private ? forPrivatePackages : workspaceWide)]));
 }
 /**
 * Resolves a plugin module name to an absolute file path, first from this tool's own module context (its peer dependencies, which every workspace installing the orchestrator must provide) and then from the workspace root (a workspace's own plugin dependencies, such as a custom changelog plugin). Both bases are named in the error when neither can resolve the name.
@@ -875,6 +934,27 @@ async function regenerateLockfile(options) {
 * Why publish is not just another semantic-release() call: semantic-release's own `run()` unconditionally derives `lastRelease` from the newest tag already on the branch matching `tagFormat`, and this mode has, by the time phase 5 runs, already created and pushed that exact tag itself. A second real `semanticRelease()` call would see its own just-created tag as the already-published release and compute the wrong next version from it. Phase 5 instead calls each resolved plugin module's own exported `verifyConditions`/`publish`/`success` functions directly, with a hand-built context -- the same public per-plugin API surface semantic-release's own core calls internally, just invoked without going through the parts of `run()` that assume a not-yet-tagged repository.
 */
 async function releaseWorkspaceSingleCommit(options) {
+	const log = options.log ?? console.log;
+	const maxAttempts = resolvePushAttempts(options.pushAttempts);
+	let lastLoss;
+	for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+		const result = await attemptSingleCommitRelease(options);
+		if (result.kind === "complete") return result.outcome;
+		if (result.kind === "pushed") {
+			await result.publish();
+			return result.outcome;
+		}
+		lastLoss = result.error;
+		log(`${packageName}: attempt ${String(attempt)} of ${String(maxAttempts)} lost the push, because ${result.branch} advanced to ${result.remoteTip} before this run's own refs reached the remote. This attempt's commit and tags have been discarded; recomputing the release against the new tip.`);
+	}
+	throw new WorkspaceStateError(`${packageName}: gave up after ${String(maxAttempts)} attempt(s) to push the release, each overtaken by another commit landing on the release branch first. Nothing was published and no tag reached the remote, so re-running is safe and loses nothing. Raise "pushAttempts" if this branch is busy enough that ${String(maxAttempts)} is genuinely too few. The last push failed with: ${lastLoss === void 0 ? "unknown" : lastLoss.message}`);
+}
+function resolvePushAttempts(configured) {
+	if (configured === void 0) return 5;
+	if (!Number.isInteger(configured) || configured < 1) throw new ReleaseConfigurationError(`"pushAttempts" must be a positive integer; received ${String(configured)}.`);
+	return configured;
+}
+async function attemptSingleCommitRelease(options) {
 	const root = resolve(options.root ?? process.cwd());
 	const log = options.log ?? console.log;
 	const dryRun = options.dryRun === true;
@@ -886,7 +966,7 @@ async function releaseWorkspaceSingleCommit(options) {
 	validateDependencyRanges(graph);
 	const order = topologicalOrder(graph);
 	log(`${packageName}: ${String(order.length)} packages in release order: ${order.join(" -> ")} (commitStrategy: single)`);
-	const resolvedPlugins = resolveWorkspacePublishPlugins(order, {
+	const resolvedPlugins = resolveWorkspacePublishPlugins(orderedPackages(graph, order), {
 		plugins: options.plugins ?? SINGLE_COMMIT_DEFAULT_PUBLISH_PLUGINS,
 		packagePlugins: options.packagePlugins
 	}, workspace.root, {
@@ -958,8 +1038,11 @@ async function releaseWorkspaceSingleCommit(options) {
 		}
 	}
 	if (dryRun || planned.length === 0) return {
-		order,
-		packages: outcomes
+		kind: "complete",
+		outcome: {
+			order,
+			packages: outcomes
+		}
 	};
 	const branch = captured.branch;
 	const repositoryUrl = captured.repositoryUrl;
@@ -998,26 +1081,51 @@ async function releaseWorkspaceSingleCommit(options) {
 	const commitSha = (await git(["rev-parse", "HEAD"], { cwd: repoRoot })).trim();
 	const tagNames = planned.map((release) => release.gitTag);
 	for (const tagName of tagNames) await createTag(tagName, commitSha, { cwd: repoRoot });
-	await pushHeadAndTags(tagNames, { cwd: repoRoot });
-	log(`${packageName}: committed ${commitSha} and pushed ${String(tagNames.length)} tag(s): ${tagNames.join(", ")}`);
-	for (const release of planned) {
-		const releases = [];
-		for (const [modulePath, pluginConfig] of mustGet(resolvedPlugins, release.pkg.name, "publish plugins")) {
-			const plugin = await loadReleasePlugin(modulePath, moduleCache);
-			if (plugin.publish) {
-				const result = await plugin.publish(pluginConfig, buildPluginContext(release, shared, capturedCommits, releases));
-				if (result !== false && result !== void 0) releases.push(result);
-			}
-		}
-		for (const [modulePath, pluginConfig] of mustGet(resolvedPlugins, release.pkg.name, "publish plugins")) {
-			const plugin = await loadReleasePlugin(modulePath, moduleCache);
-			if (plugin.success) await plugin.success(pluginConfig, buildPluginContext(release, shared, capturedCommits, releases));
+	const branchName = await currentBranch({ cwd: repoRoot });
+	try {
+		await pushHeadAndTags(tagNames, { cwd: repoRoot });
+	} catch (error) {
+		if (!(error instanceof GitCommandError)) throw error;
+		let remoteTip;
+		try {
+			remoteTip = await fetchBranchTip(branchName, { cwd: repoRoot });
+		} catch {
+			throw error;
 		}
-		log(`${release.pkg.name}: published ${release.gitTag}`);
+		if (await isAncestor(remoteTip, "HEAD", { cwd: repoRoot })) throw error;
+		await deleteLocalTags(tagNames, { cwd: repoRoot });
+		await resetHardTo(remoteTip, { cwd: repoRoot });
+		return {
+			kind: "lost",
+			error,
+			branch: branchName,
+			remoteTip
+		};
 	}
+	log(`${packageName}: committed ${commitSha} and pushed ${String(tagNames.length)} tag(s): ${tagNames.join(", ")}`);
 	return {
-		order,
-		packages: outcomes
+		kind: "pushed",
+		outcome: {
+			order,
+			packages: outcomes
+		},
+		publish: async () => {
+			for (const release of planned) {
+				const releases = [];
+				for (const [modulePath, pluginConfig] of mustGet(resolvedPlugins, release.pkg.name, "publish plugins")) {
+					const plugin = await loadReleasePlugin(modulePath, moduleCache);
+					if (plugin.publish) {
+						const result = await plugin.publish(pluginConfig, buildPluginContext(release, shared, capturedCommits, releases));
+						if (result !== false && result !== void 0) releases.push(result);
+					}
+				}
+				for (const [modulePath, pluginConfig] of mustGet(resolvedPlugins, release.pkg.name, "publish plugins")) {
+					const plugin = await loadReleasePlugin(modulePath, moduleCache);
+					if (plugin.success) await plugin.success(pluginConfig, buildPluginContext(release, shared, capturedCommits, releases));
+				}
+				log(`${release.pkg.name}: published ${release.gitTag}`);
+			}
+		}
 	};
 }
 /**
@@ -1170,7 +1278,7 @@ async function releaseWorkspace(options = {}) {
 	validateDependencyRanges(graph);
 	const order = topologicalOrder(graph);
 	log(`${packageName}: ${String(order.length)} packages in release order: ${order.join(" -> ")}`);
-	const publishPlugins = resolveWorkspacePublishPlugins(order, {
+	const publishPlugins = resolveWorkspacePublishPlugins(orderedPackages(graph, order), {
 		plugins: options.plugins ?? DEFAULT_PUBLISH_PLUGINS,
 		packagePlugins: options.packagePlugins
 	}, workspace.root, { requireGitPlugin: !dryRun });
@@ -1337,7 +1445,7 @@ async function detachWorkspaceRelease(options) {
 	validateDependencyRanges(graph);
 	const order = topologicalOrder(graph);
 	log(`${packageName}: ${String(order.length)} packages in release order (gated -- tag only, publish deferred): ${order.join(" -> ")}`);
-	const publishPlugins = resolveWorkspacePublishPlugins(order, {
+	const publishPlugins = resolveWorkspacePublishPlugins(orderedPackages(graph, order), {
 		plugins: options.plugins ?? DEFAULT_PUBLISH_PLUGINS,
 		packagePlugins: options.packagePlugins
 	}, workspace.root, { requireGitPlugin: !dryRun });

package/dist/index.cjs

@@ -286,6 +286,53 @@ async function pushHeadAndTags(tagNames, options) {
 		...tagNames
 	], options);
 }
+/**
+* Fetches `branch` from origin and returns the commit it now points at.
+*
+* This is how a failed push is classified, in preference to reading the reason git printed for the rejection. The wording is not stable enough to branch on: the same race produces `! [rejected] ... (non-fast-forward)` from one server and `cannot lock ref 'refs/heads/main': is at <x> but expected <y>` from another (both observed, the first against GitHub and the second against a local bare repository under `--atomic`), and neither is a documented interface. Whether the branch actually moved is a fact about the remote rather than a string, it is the precise condition a retry can recover from, and it is knowable by asking.
+*/
+async function fetchBranchTip(branch, options) {
+	await git([
+		"fetch",
+		"origin",
+		branch
+	], options);
+	return (await git(["rev-parse", "FETCH_HEAD"], options)).trim();
+}
+/** Whether `ancestor` is reachable from `descendant`. `git merge-base --is-ancestor` reports the answer as an exit status rather than on stdout: 0 for yes and 1 for no are both answers, so only any other exit code is a failure. */
+async function isAncestor(ancestor, descendant, options) {
+	const args = [
+		"merge-base",
+		"--is-ancestor",
+		ancestor,
+		descendant
+	];
+	try {
+		await execGit(args, options.cwd);
+		return true;
+	} catch (cause) {
+		const error = toGitCommandError(args, options.cwd, cause);
+		if (error.exitCode === 1) return false;
+		throw error;
+	}
+}
+/** Discards every commit and working-tree change the current attempt made, putting the checkout back on exactly `ref`. */
+async function resetHardTo(ref, options) {
+	await git([
+		"reset",
+		"--hard",
+		ref
+	], options);
+}
+/** Deletes local tags. A retried attempt must drop the tags its predecessor created before it recreates them: `git tag` refuses a name that already exists, so without this the second attempt fails while tagging, before it ever reaches the push it was retrying. */
+async function deleteLocalTags(tagNames, options) {
+	if (tagNames.length === 0) return;
+	await git([
+		"tag",
+		"-d",
+		...tagNames
+	], options);
+}
 function toGitCommandError(args, cwd, cause) {
 	const exitCode = cause instanceof Error && "code" in cause && typeof cause.code === "number" ? cause.code : void 0;
 	const stderr = cause instanceof Error && "stderr" in cause && typeof cause.stderr === "string" ? cause.stderr.trim() : "";
@@ -603,6 +650,10 @@ function topologicalOrder(graph) {
 	if (pending.size > 0) throw new DependencyCycleError(findCycle(graph, new Set(pending.keys())));
 	return ordered;
 }
+/** The packages a release order names, in that order, for the stages that need each package's manifest rather than only its name. */
+function orderedPackages(graph, order) {
+	return order.map((name) => mustGet(graph.packages, name, "package"));
+}
 /**
 * Walks dependency edges between the packages Kahn's algorithm could not place, until it revisits one, so the error can name a concrete loop rather than just a set of packages. Every unplaced package is unplaced precisely because at least one of its own dependencies is too, so the walk always reaches a repeat.
 */
@@ -681,6 +732,8 @@ function matchTrailerLine(message, key) {
 }
 //#endregion
 //#region src/plugins.ts
+/** The one plugin a private package is kept off by default: see `resolveWorkspacePublishPlugins` for why a package that never reaches a registry does not get a public GitHub Release either. */
+const GITHUB_RELEASE_PLUGIN = "@semantic-release/github";
 /** semantic-release's own `getLastRelease` returns `{}` for a package with no prior tag -- not `undefined`, and not a fully-populated `LastRelease` -- contradicting the `gitHead: string` its own type declares. Narrows structurally rather than trusting that declared type, so a first-release context's `lastRelease` (correctly, at runtime) never claims a `gitHead` it does not have. */
 function hasGitHead(lastRelease) {
 	return typeof lastRelease === "object" && lastRelease !== null && "gitHead" in lastRelease && typeof lastRelease.gitHead === "string";
@@ -807,13 +860,17 @@ function resolvePublishPlugins(specs, workspaceRoot, options) {
 /**
 * Resolves the publish plugin list of every package in the workspace: the workspace-wide list for each package, except where `packagePlugins` names a package, whose own list replaces it. Every list is held to the same rules as `resolvePublishPlugins` applies to a workspace-wide one, and a failure in an override names the package it belongs to.
 *
+* A package whose manifest sets `private: true` and which no `packagePlugins` entry names gets the workspace-wide list minus `@semantic-release/github`. A private package is never published, so a public GitHub Release for it advertises something nobody can install, and that release is not merely redundant: `@semantic-release/github` sets `make_latest` from the release branch alone, with no option to opt out, so every release it creates claims the repository's Latest label and the last one created keeps it. A private package sitting at the end of the topological order (which is where a package that depends on the published ones necessarily sits) therefore takes the label on every run. Everything the private package actually needs from the run is untouched: its version bump, its tag, and the dependency cascade to its dependents all come from the other plugins and from the orchestrator itself.
+*
+* A `packagePlugins` entry naming a private package is taken exactly as written, `@semantic-release/github` included, so a workspace that does want a Release for a private package can still say so.
+*
 * A `packagePlugins` key that matches no package is rejected rather than ignored: a misspelt name would otherwise leave the package it meant on the workspace-wide list with nothing to say so, which for the intended use (keeping a package out of a step such as GitHub Release creation) is a silent wrong result.
 */
-function resolveWorkspacePublishPlugins(packageNames, specs, workspaceRoot, options) {
+function resolveWorkspacePublishPlugins(packages, specs, workspaceRoot, options) {
 	const overrides = specs.packagePlugins === void 0 ? [] : Object.entries(specs.packagePlugins);
-	const known = new Set(packageNames);
+	const known = new Set(packages.map((pkg) => pkg.name));
 	const unknown = overrides.map(([name]) => name).filter((name) => !known.has(name));
-	if (unknown.length > 0) throw new ReleaseConfigurationError(`packagePlugins names ${unknown.map((name) => `"${name}"`).join(", ")}, which ${unknown.length === 1 ? "is" : "are"} not a package in this workspace. Packages: ${packageNames.join(", ")}.`);
+	if (unknown.length > 0) throw new ReleaseConfigurationError(`packagePlugins names ${unknown.map((name) => `"${name}"`).join(", ")}, which ${unknown.length === 1 ? "is" : "are"} not a package in this workspace. Packages: ${[...known].join(", ")}.`);
 	const workspaceWide = resolvePublishPlugins(specs.plugins, workspaceRoot, options);
 	const resolvedOverrides = /* @__PURE__ */ new Map();
 	for (const [name, list] of overrides) try {
@@ -822,7 +879,9 @@ function resolveWorkspacePublishPlugins(packageNames, specs, workspaceRoot, opti
 		if (cause instanceof ReleaseConfigurationError) throw new ReleaseConfigurationError(`packagePlugins for "${name}": ${cause.message}`);
 		throw cause;
 	}
-	return new Map(packageNames.map((name) => [name, resolvedOverrides.get(name) ?? workspaceWide]));
+	const privateSpecs = specs.plugins.filter((spec) => parsePublishPluginSpec(spec)[0] !== GITHUB_RELEASE_PLUGIN);
+	const forPrivatePackages = privateSpecs.length === specs.plugins.length ? workspaceWide : resolvePublishPlugins(privateSpecs, workspaceRoot, options);
+	return new Map(packages.map((pkg) => [pkg.name, resolvedOverrides.get(pkg.name) ?? (pkg.private ? forPrivatePackages : workspaceWide)]));
 }
 /**
 * Resolves a plugin module name to an absolute file path, first from this tool's own module context (its peer dependencies, which every workspace installing the orchestrator must provide) and then from the workspace root (a workspace's own plugin dependencies, such as a custom changelog plugin). Both bases are named in the error when neither can resolve the name.
@@ -888,6 +947,27 @@ function formatTagForPackage(tagFormat, name) {
 * Why publish is not just another semantic-release() call: semantic-release's own `run()` unconditionally derives `lastRelease` from the newest tag already on the branch matching `tagFormat`, and this mode has, by the time phase 5 runs, already created and pushed that exact tag itself. A second real `semanticRelease()` call would see its own just-created tag as the already-published release and compute the wrong next version from it. Phase 5 instead calls each resolved plugin module's own exported `verifyConditions`/`publish`/`success` functions directly, with a hand-built context -- the same public per-plugin API surface semantic-release's own core calls internally, just invoked without going through the parts of `run()` that assume a not-yet-tagged repository.
 */
 async function releaseWorkspaceSingleCommit(options) {
+	const log = options.log ?? console.log;
+	const maxAttempts = resolvePushAttempts(options.pushAttempts);
+	let lastLoss;
+	for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+		const result = await attemptSingleCommitRelease(options);
+		if (result.kind === "complete") return result.outcome;
+		if (result.kind === "pushed") {
+			await result.publish();
+			return result.outcome;
+		}
+		lastLoss = result.error;
+		log(`${packageName}: attempt ${String(attempt)} of ${String(maxAttempts)} lost the push, because ${result.branch} advanced to ${result.remoteTip} before this run's own refs reached the remote. This attempt's commit and tags have been discarded; recomputing the release against the new tip.`);
+	}
+	throw new WorkspaceStateError(`${packageName}: gave up after ${String(maxAttempts)} attempt(s) to push the release, each overtaken by another commit landing on the release branch first. Nothing was published and no tag reached the remote, so re-running is safe and loses nothing. Raise "pushAttempts" if this branch is busy enough that ${String(maxAttempts)} is genuinely too few. The last push failed with: ${lastLoss === void 0 ? "unknown" : lastLoss.message}`);
+}
+function resolvePushAttempts(configured) {
+	if (configured === void 0) return 5;
+	if (!Number.isInteger(configured) || configured < 1) throw new ReleaseConfigurationError(`"pushAttempts" must be a positive integer; received ${String(configured)}.`);
+	return configured;
+}
+async function attemptSingleCommitRelease(options) {
 	const root = (0, node_path.resolve)(options.root ?? process.cwd());
 	const log = options.log ?? console.log;
 	const dryRun = options.dryRun === true;
@@ -899,7 +979,7 @@ async function releaseWorkspaceSingleCommit(options) {
 	validateDependencyRanges(graph);
 	const order = topologicalOrder(graph);
 	log(`${packageName}: ${String(order.length)} packages in release order: ${order.join(" -> ")} (commitStrategy: single)`);
-	const resolvedPlugins = resolveWorkspacePublishPlugins(order, {
+	const resolvedPlugins = resolveWorkspacePublishPlugins(orderedPackages(graph, order), {
 		plugins: options.plugins ?? SINGLE_COMMIT_DEFAULT_PUBLISH_PLUGINS,
 		packagePlugins: options.packagePlugins
 	}, workspace.root, {
@@ -971,8 +1051,11 @@ async function releaseWorkspaceSingleCommit(options) {
 		}
 	}
 	if (dryRun || planned.length === 0) return {
-		order,
-		packages: outcomes
+		kind: "complete",
+		outcome: {
+			order,
+			packages: outcomes
+		}
 	};
 	const branch = captured.branch;
 	const repositoryUrl = captured.repositoryUrl;
@@ -1011,26 +1094,51 @@ async function releaseWorkspaceSingleCommit(options) {
 	const commitSha = (await git(["rev-parse", "HEAD"], { cwd: repoRoot })).trim();
 	const tagNames = planned.map((release) => release.gitTag);
 	for (const tagName of tagNames) await createTag(tagName, commitSha, { cwd: repoRoot });
-	await pushHeadAndTags(tagNames, { cwd: repoRoot });
-	log(`${packageName}: committed ${commitSha} and pushed ${String(tagNames.length)} tag(s): ${tagNames.join(", ")}`);
-	for (const release of planned) {
-		const releases = [];
-		for (const [modulePath, pluginConfig] of mustGet(resolvedPlugins, release.pkg.name, "publish plugins")) {
-			const plugin = await loadReleasePlugin(modulePath, moduleCache);
-			if (plugin.publish) {
-				const result = await plugin.publish(pluginConfig, buildPluginContext(release, shared, capturedCommits, releases));
-				if (result !== false && result !== void 0) releases.push(result);
-			}
-		}
-		for (const [modulePath, pluginConfig] of mustGet(resolvedPlugins, release.pkg.name, "publish plugins")) {
-			const plugin = await loadReleasePlugin(modulePath, moduleCache);
-			if (plugin.success) await plugin.success(pluginConfig, buildPluginContext(release, shared, capturedCommits, releases));
+	const branchName = await currentBranch({ cwd: repoRoot });
+	try {
+		await pushHeadAndTags(tagNames, { cwd: repoRoot });
+	} catch (error) {
+		if (!(error instanceof GitCommandError)) throw error;
+		let remoteTip;
+		try {
+			remoteTip = await fetchBranchTip(branchName, { cwd: repoRoot });
+		} catch {
+			throw error;
 		}
-		log(`${release.pkg.name}: published ${release.gitTag}`);
+		if (await isAncestor(remoteTip, "HEAD", { cwd: repoRoot })) throw error;
+		await deleteLocalTags(tagNames, { cwd: repoRoot });
+		await resetHardTo(remoteTip, { cwd: repoRoot });
+		return {
+			kind: "lost",
+			error,
+			branch: branchName,
+			remoteTip
+		};
 	}
+	log(`${packageName}: committed ${commitSha} and pushed ${String(tagNames.length)} tag(s): ${tagNames.join(", ")}`);
 	return {
-		order,
-		packages: outcomes
+		kind: "pushed",
+		outcome: {
+			order,
+			packages: outcomes
+		},
+		publish: async () => {
+			for (const release of planned) {
+				const releases = [];
+				for (const [modulePath, pluginConfig] of mustGet(resolvedPlugins, release.pkg.name, "publish plugins")) {
+					const plugin = await loadReleasePlugin(modulePath, moduleCache);
+					if (plugin.publish) {
+						const result = await plugin.publish(pluginConfig, buildPluginContext(release, shared, capturedCommits, releases));
+						if (result !== false && result !== void 0) releases.push(result);
+					}
+				}
+				for (const [modulePath, pluginConfig] of mustGet(resolvedPlugins, release.pkg.name, "publish plugins")) {
+					const plugin = await loadReleasePlugin(modulePath, moduleCache);
+					if (plugin.success) await plugin.success(pluginConfig, buildPluginContext(release, shared, capturedCommits, releases));
+				}
+				log(`${release.pkg.name}: published ${release.gitTag}`);
+			}
+		}
 	};
 }
 /**
@@ -1176,7 +1284,7 @@ async function detachWorkspaceRelease(options) {
 	validateDependencyRanges(graph);
 	const order = topologicalOrder(graph);
 	log(`${packageName}: ${String(order.length)} packages in release order (gated -- tag only, publish deferred): ${order.join(" -> ")}`);
-	const publishPlugins = resolveWorkspacePublishPlugins(order, {
+	const publishPlugins = resolveWorkspacePublishPlugins(orderedPackages(graph, order), {
 		plugins: options.plugins ?? DEFAULT_PUBLISH_PLUGINS,
 		packagePlugins: options.packagePlugins
 	}, workspace.root, { requireGitPlugin: !dryRun });
@@ -1318,7 +1426,7 @@ async function releaseWorkspace(options = {}) {
 	validateDependencyRanges(graph);
 	const order = topologicalOrder(graph);
 	log(`${packageName}: ${String(order.length)} packages in release order: ${order.join(" -> ")}`);
-	const publishPlugins = resolveWorkspacePublishPlugins(order, {
+	const publishPlugins = resolveWorkspacePublishPlugins(orderedPackages(graph, order), {
 		plugins: options.plugins ?? DEFAULT_PUBLISH_PLUGINS,
 		packagePlugins: options.packagePlugins
 	}, workspace.root, { requireGitPlugin: !dryRun });
@@ -1485,6 +1593,7 @@ exports.classifyDependencyRange = classifyDependencyRange;
 exports.createScopedPlugins = createScopedPlugins;
 exports.discoverWorkspace = discoverWorkspace;
 exports.filterCommitsToDirectory = filterCommitsToDirectory;
+exports.orderedPackages = orderedPackages;
 exports.packageName = packageName;
 exports.readManifest = readManifest;
 exports.releaseWorkspace = releaseWorkspace;

package/dist/index.d.cts

@@ -86,6 +86,8 @@ export declare function buildDependencyGraph(packages: readonly WorkspacePackage
  * A cycle has no valid order at all, so it throws rather than picking one of the wrong answers. In a release context an arbitrary order is worse than a failure: it would publish a package whose sibling dependency range points at a version that does not exist yet.
  */
 export declare function topologicalOrder(graph: DependencyGraph): readonly string[];
+/** The packages a release order names, in that order, for the stages that need each package's manifest rather than only its name. */
+export declare function orderedPackages(graph: DependencyGraph, order: readonly string[]): readonly WorkspacePackage[];
 //#endregion
 //#region src/version-range.d.ts
 /**
@@ -149,6 +151,11 @@ interface DependencyBumpSource {
 type PublishPluginSpec = string | readonly [string] | readonly [string, Record<string, unknown>];
 /** Publish plugin lists keyed by package name. Each list replaces the workspace-wide list outright for that one package; it is not merged with it. */
 type PackagePluginSpecs = Readonly<Record<string, readonly PublishPluginSpec[]>>;
+/** All resolving a package's publish plugins needs to know about it: its name, and whether its manifest marks it private. `WorkspacePackage` satisfies this structurally. */
+interface PublishPluginPackage {
+  readonly name: string;
+  readonly private: boolean;
+}
 /** The standard publish pipeline this orchestrator coordinates when a workspace configures none of its own. Every entry reuses the corresponding official plugin -- the orchestrator scopes and sequences them per package, it does not reimplement npm publishing, GitHub release creation, or changelog writing. */
 export declare const DEFAULT_PUBLISH_PLUGINS: readonly PublishPluginSpec[];
 /** The standard publish pipeline for `commitStrategy: 'single'`: the same as `DEFAULT_PUBLISH_PLUGINS` minus `@semantic-release/git`, which that mode never runs -- see `resolvePublishPlugins`'s `forbidGitPlugin` option for why it is rejected outright rather than merely unused. Single-commit mode does its own committing (one combined commit for every released package), so a `prepare`-step git plugin here would create the very per-package commits that mode exists to avoid. */
@@ -193,9 +200,13 @@ export declare function resolvePublishPlugins(specs: readonly PublishPluginSpec[
 /**
  * Resolves the publish plugin list of every package in the workspace: the workspace-wide list for each package, except where `packagePlugins` names a package, whose own list replaces it. Every list is held to the same rules as `resolvePublishPlugins` applies to a workspace-wide one, and a failure in an override names the package it belongs to.
  *
+ * A package whose manifest sets `private: true` and which no `packagePlugins` entry names gets the workspace-wide list minus `@semantic-release/github`. A private package is never published, so a public GitHub Release for it advertises something nobody can install, and that release is not merely redundant: `@semantic-release/github` sets `make_latest` from the release branch alone, with no option to opt out, so every release it creates claims the repository's Latest label and the last one created keeps it. A private package sitting at the end of the topological order (which is where a package that depends on the published ones necessarily sits) therefore takes the label on every run. Everything the private package actually needs from the run is untouched: its version bump, its tag, and the dependency cascade to its dependents all come from the other plugins and from the orchestrator itself.
+ *
+ * A `packagePlugins` entry naming a private package is taken exactly as written, `@semantic-release/github` included, so a workspace that does want a Release for a private package can still say so.
+ *
  * A `packagePlugins` key that matches no package is rejected rather than ignored: a misspelt name would otherwise leave the package it meant on the workspace-wide list with nothing to say so, which for the intended use (keeping a package out of a step such as GitHub Release creation) is a silent wrong result.
  */
-export declare function resolveWorkspacePublishPlugins(packageNames: readonly string[], specs: {
+export declare function resolveWorkspacePublishPlugins(packages: readonly PublishPluginPackage[], specs: {
   readonly plugins: readonly PublishPluginSpec[];
   readonly packagePlugins: PackagePluginSpecs | undefined;
 }, workspaceRoot: string, options: {
@@ -246,7 +257,7 @@ interface ReleaseWorkspaceOptions {
   readonly branches?: readonly BranchSpec[];
   /** Publish-pipeline plugins (changelog, npm, GitHub, git), each scoped per package by semantic-release's own `cwd`. Defaults to the standard pipeline in DEFAULT_PUBLISH_PLUGINS for `commitStrategy: 'per-package'`, or SINGLE_COMMIT_DEFAULT_PUBLISH_PLUGINS (the same list minus `@semantic-release/git`) for `commitStrategy: 'single'`. */
   readonly plugins?: readonly PublishPluginSpec[];
-  /** Publish plugin lists for individual packages, keyed by package name, each replacing `plugins` (or its default) outright for that package. Every other package keeps the workspace-wide list. The usual use is keeping one package out of a step the rest need, for example leaving `@semantic-release/github` off a private package so it gets its tag, version bump and dependency cascade without a public GitHub Release. Applies under every `commitStrategy` and to `gatePublish`. A name that is not a package in the workspace is rejected. */
+  /** Publish plugin lists for individual packages, keyed by package name, each replacing `plugins` (or its default) outright for that package. Every other package keeps the workspace-wide list, except that a package marked `private` in its manifest drops `@semantic-release/github` from it on its own (see `resolveWorkspacePublishPlugins`), so the usual reason to reach for this is either the reverse of that default, a private package that does want a GitHub Release, or keeping a package out of some other step the rest need. Applies under every `commitStrategy` and to `gatePublish`. A name that is not a package in the workspace is rejected. */
   readonly packagePlugins?: PackagePluginSpecs;
   /** Options for the wrapped `@semantic-release/commit-analyzer`, applied per package after path filtering. */
   readonly analyzeCommits?: Record<string, unknown>;
@@ -268,6 +279,14 @@ interface ReleaseWorkspaceOptions {
    * and pins `...@<action>-v1`. Validated once per run by `validateTagFormat`.
    */
   readonly tagFormat?: string;
+  /**
+   * How many times `commitStrategy: 'single'` will compute and push a release before giving up, when each attempt is lost to another commit landing on the release branch first. Defaults to `DEFAULT_PUSH_ATTEMPTS`. Ignored by `commitStrategy: 'per-package'`, which pushes incrementally and has no all-or-nothing attempt to repeat.
+   *
+   * The default is derived rather than chosen. An attempt is lost if any commit lands during its own window, so with pushes arriving at rate `L` and an attempt taking `W`, an attempt survives with probability `e^(-L*W)` and `n` attempts all fail with probability `(1 - e^(-L*W))^n`. On the busiest repository this tool serves, pushes to the release branch arrived at roughly one every 7.4 minutes while a merge queue was landing pull requests continuously (measured over the busiest 60, 90 and 120 minute windows, which agreed to within 6%), and analysing, preparing, committing and pushing 23 packages took about 2.2 minutes, so `W = 3` minutes leaves headroom for a larger workspace. That gives about a one-in-three chance of losing any single attempt, which matches what was observed when there was no retry at all, and 5 attempts put the chance of losing all of them near 0.4%, or roughly one lost release a month at ten releases a day. Five attempts also bound the added time at about 15 minutes, well inside the hour-long job timeouts these releases run under.
+   *
+   * Raise it for a busier branch or a slower workspace; the cost of a higher bound is only paid when attempts are actually being lost.
+   */
+  readonly pushAttempts?: number;
 }
 /** One dependency-range change applied to a dependent package's manifest during the run, attached to the dependent's own outcome. */
 interface AppliedDependencyBump extends DependencyBump {
@@ -334,4 +353,4 @@ export declare class GitCommandError extends WorkspaceReleaseError {
 /** The workspace's git state does not support the release operation -- for example a detached HEAD, which names no branch that dependency-bump commits could be pushed to. */
 export declare class WorkspaceStateError extends WorkspaceReleaseError {}
 //#endregion
-export type { AppliedDependencyBump, CommitStrategy, DependencyBump, DependencyBumpSource, DependencyField, DependencyGraph, DependencyRangeShape, DependencyRangeUpdate, DetachedPackageRelease, PackageManifest, PackagePluginSpecs, PackageReleaseOutcome, PublishPluginSpec, ReleaseWorkspaceOptions, ResolvedPublishPlugin, ResumeWorkspaceReleaseOptions, ScopedPlugins, Workspace, WorkspaceDependency, WorkspacePackage, WorkspaceReleaseOutcome };
+export type { AppliedDependencyBump, CommitStrategy, DependencyBump, DependencyBumpSource, DependencyField, DependencyGraph, DependencyRangeShape, DependencyRangeUpdate, DetachedPackageRelease, PackageManifest, PackagePluginSpecs, PackageReleaseOutcome, PublishPluginPackage, PublishPluginSpec, ReleaseWorkspaceOptions, ResolvedPublishPlugin, ResumeWorkspaceReleaseOptions, ScopedPlugins, Workspace, WorkspaceDependency, WorkspacePackage, WorkspaceReleaseOutcome };

package/dist/index.d.ts

@@ -86,6 +86,8 @@ export declare function buildDependencyGraph(packages: readonly WorkspacePackage
  * A cycle has no valid order at all, so it throws rather than picking one of the wrong answers. In a release context an arbitrary order is worse than a failure: it would publish a package whose sibling dependency range points at a version that does not exist yet.
  */
 export declare function topologicalOrder(graph: DependencyGraph): readonly string[];
+/** The packages a release order names, in that order, for the stages that need each package's manifest rather than only its name. */
+export declare function orderedPackages(graph: DependencyGraph, order: readonly string[]): readonly WorkspacePackage[];
 //#endregion
 //#region src/version-range.d.ts
 /**
@@ -149,6 +151,11 @@ interface DependencyBumpSource {
 type PublishPluginSpec = string | readonly [string] | readonly [string, Record<string, unknown>];
 /** Publish plugin lists keyed by package name. Each list replaces the workspace-wide list outright for that one package; it is not merged with it. */
 type PackagePluginSpecs = Readonly<Record<string, readonly PublishPluginSpec[]>>;
+/** All resolving a package's publish plugins needs to know about it: its name, and whether its manifest marks it private. `WorkspacePackage` satisfies this structurally. */
+interface PublishPluginPackage {
+  readonly name: string;
+  readonly private: boolean;
+}
 /** The standard publish pipeline this orchestrator coordinates when a workspace configures none of its own. Every entry reuses the corresponding official plugin -- the orchestrator scopes and sequences them per package, it does not reimplement npm publishing, GitHub release creation, or changelog writing. */
 export declare const DEFAULT_PUBLISH_PLUGINS: readonly PublishPluginSpec[];
 /** The standard publish pipeline for `commitStrategy: 'single'`: the same as `DEFAULT_PUBLISH_PLUGINS` minus `@semantic-release/git`, which that mode never runs -- see `resolvePublishPlugins`'s `forbidGitPlugin` option for why it is rejected outright rather than merely unused. Single-commit mode does its own committing (one combined commit for every released package), so a `prepare`-step git plugin here would create the very per-package commits that mode exists to avoid. */
@@ -193,9 +200,13 @@ export declare function resolvePublishPlugins(specs: readonly PublishPluginSpec[
 /**
  * Resolves the publish plugin list of every package in the workspace: the workspace-wide list for each package, except where `packagePlugins` names a package, whose own list replaces it. Every list is held to the same rules as `resolvePublishPlugins` applies to a workspace-wide one, and a failure in an override names the package it belongs to.
  *
+ * A package whose manifest sets `private: true` and which no `packagePlugins` entry names gets the workspace-wide list minus `@semantic-release/github`. A private package is never published, so a public GitHub Release for it advertises something nobody can install, and that release is not merely redundant: `@semantic-release/github` sets `make_latest` from the release branch alone, with no option to opt out, so every release it creates claims the repository's Latest label and the last one created keeps it. A private package sitting at the end of the topological order (which is where a package that depends on the published ones necessarily sits) therefore takes the label on every run. Everything the private package actually needs from the run is untouched: its version bump, its tag, and the dependency cascade to its dependents all come from the other plugins and from the orchestrator itself.
+ *
+ * A `packagePlugins` entry naming a private package is taken exactly as written, `@semantic-release/github` included, so a workspace that does want a Release for a private package can still say so.
+ *
  * A `packagePlugins` key that matches no package is rejected rather than ignored: a misspelt name would otherwise leave the package it meant on the workspace-wide list with nothing to say so, which for the intended use (keeping a package out of a step such as GitHub Release creation) is a silent wrong result.
  */
-export declare function resolveWorkspacePublishPlugins(packageNames: readonly string[], specs: {
+export declare function resolveWorkspacePublishPlugins(packages: readonly PublishPluginPackage[], specs: {
   readonly plugins: readonly PublishPluginSpec[];
   readonly packagePlugins: PackagePluginSpecs | undefined;
 }, workspaceRoot: string, options: {
@@ -246,7 +257,7 @@ interface ReleaseWorkspaceOptions {
   readonly branches?: readonly BranchSpec[];
   /** Publish-pipeline plugins (changelog, npm, GitHub, git), each scoped per package by semantic-release's own `cwd`. Defaults to the standard pipeline in DEFAULT_PUBLISH_PLUGINS for `commitStrategy: 'per-package'`, or SINGLE_COMMIT_DEFAULT_PUBLISH_PLUGINS (the same list minus `@semantic-release/git`) for `commitStrategy: 'single'`. */
   readonly plugins?: readonly PublishPluginSpec[];
-  /** Publish plugin lists for individual packages, keyed by package name, each replacing `plugins` (or its default) outright for that package. Every other package keeps the workspace-wide list. The usual use is keeping one package out of a step the rest need, for example leaving `@semantic-release/github` off a private package so it gets its tag, version bump and dependency cascade without a public GitHub Release. Applies under every `commitStrategy` and to `gatePublish`. A name that is not a package in the workspace is rejected. */
+  /** Publish plugin lists for individual packages, keyed by package name, each replacing `plugins` (or its default) outright for that package. Every other package keeps the workspace-wide list, except that a package marked `private` in its manifest drops `@semantic-release/github` from it on its own (see `resolveWorkspacePublishPlugins`), so the usual reason to reach for this is either the reverse of that default, a private package that does want a GitHub Release, or keeping a package out of some other step the rest need. Applies under every `commitStrategy` and to `gatePublish`. A name that is not a package in the workspace is rejected. */
   readonly packagePlugins?: PackagePluginSpecs;
   /** Options for the wrapped `@semantic-release/commit-analyzer`, applied per package after path filtering. */
   readonly analyzeCommits?: Record<string, unknown>;
@@ -268,6 +279,14 @@ interface ReleaseWorkspaceOptions {
    * and pins `...@<action>-v1`. Validated once per run by `validateTagFormat`.
    */
   readonly tagFormat?: string;
+  /**
+   * How many times `commitStrategy: 'single'` will compute and push a release before giving up, when each attempt is lost to another commit landing on the release branch first. Defaults to `DEFAULT_PUSH_ATTEMPTS`. Ignored by `commitStrategy: 'per-package'`, which pushes incrementally and has no all-or-nothing attempt to repeat.
+   *
+   * The default is derived rather than chosen. An attempt is lost if any commit lands during its own window, so with pushes arriving at rate `L` and an attempt taking `W`, an attempt survives with probability `e^(-L*W)` and `n` attempts all fail with probability `(1 - e^(-L*W))^n`. On the busiest repository this tool serves, pushes to the release branch arrived at roughly one every 7.4 minutes while a merge queue was landing pull requests continuously (measured over the busiest 60, 90 and 120 minute windows, which agreed to within 6%), and analysing, preparing, committing and pushing 23 packages took about 2.2 minutes, so `W = 3` minutes leaves headroom for a larger workspace. That gives about a one-in-three chance of losing any single attempt, which matches what was observed when there was no retry at all, and 5 attempts put the chance of losing all of them near 0.4%, or roughly one lost release a month at ten releases a day. Five attempts also bound the added time at about 15 minutes, well inside the hour-long job timeouts these releases run under.
+   *
+   * Raise it for a busier branch or a slower workspace; the cost of a higher bound is only paid when attempts are actually being lost.
+   */
+  readonly pushAttempts?: number;
 }
 /** One dependency-range change applied to a dependent package's manifest during the run, attached to the dependent's own outcome. */
 interface AppliedDependencyBump extends DependencyBump {
@@ -334,4 +353,4 @@ export declare class GitCommandError extends WorkspaceReleaseError {
 /** The workspace's git state does not support the release operation -- for example a detached HEAD, which names no branch that dependency-bump commits could be pushed to. */
 export declare class WorkspaceStateError extends WorkspaceReleaseError {}
 //#endregion
-export type { AppliedDependencyBump, CommitStrategy, DependencyBump, DependencyBumpSource, DependencyField, DependencyGraph, DependencyRangeShape, DependencyRangeUpdate, DetachedPackageRelease, PackageManifest, PackagePluginSpecs, PackageReleaseOutcome, PublishPluginSpec, ReleaseWorkspaceOptions, ResolvedPublishPlugin, ResumeWorkspaceReleaseOptions, ScopedPlugins, Workspace, WorkspaceDependency, WorkspacePackage, WorkspaceReleaseOutcome };
+export type { AppliedDependencyBump, CommitStrategy, DependencyBump, DependencyBumpSource, DependencyField, DependencyGraph, DependencyRangeShape, DependencyRangeUpdate, DetachedPackageRelease, PackageManifest, PackagePluginSpecs, PackageReleaseOutcome, PublishPluginPackage, PublishPluginSpec, ReleaseWorkspaceOptions, ResolvedPublishPlugin, ResumeWorkspaceReleaseOptions, ScopedPlugins, Workspace, WorkspaceDependency, WorkspacePackage, WorkspaceReleaseOutcome };

package/dist/index.js

@@ -261,6 +261,53 @@ async function pushHeadAndTags(tagNames, options) {
 		...tagNames
 	], options);
 }
+/**
+* Fetches `branch` from origin and returns the commit it now points at.
+*
+* This is how a failed push is classified, in preference to reading the reason git printed for the rejection. The wording is not stable enough to branch on: the same race produces `! [rejected] ... (non-fast-forward)` from one server and `cannot lock ref 'refs/heads/main': is at <x> but expected <y>` from another (both observed, the first against GitHub and the second against a local bare repository under `--atomic`), and neither is a documented interface. Whether the branch actually moved is a fact about the remote rather than a string, it is the precise condition a retry can recover from, and it is knowable by asking.
+*/
+async function fetchBranchTip(branch, options) {
+	await git([
+		"fetch",
+		"origin",
+		branch
+	], options);
+	return (await git(["rev-parse", "FETCH_HEAD"], options)).trim();
+}
+/** Whether `ancestor` is reachable from `descendant`. `git merge-base --is-ancestor` reports the answer as an exit status rather than on stdout: 0 for yes and 1 for no are both answers, so only any other exit code is a failure. */
+async function isAncestor(ancestor, descendant, options) {
+	const args = [
+		"merge-base",
+		"--is-ancestor",
+		ancestor,
+		descendant
+	];
+	try {
+		await execGit(args, options.cwd);
+		return true;
+	} catch (cause) {
+		const error = toGitCommandError(args, options.cwd, cause);
+		if (error.exitCode === 1) return false;
+		throw error;
+	}
+}
+/** Discards every commit and working-tree change the current attempt made, putting the checkout back on exactly `ref`. */
+async function resetHardTo(ref, options) {
+	await git([
+		"reset",
+		"--hard",
+		ref
+	], options);
+}
+/** Deletes local tags. A retried attempt must drop the tags its predecessor created before it recreates them: `git tag` refuses a name that already exists, so without this the second attempt fails while tagging, before it ever reaches the push it was retrying. */
+async function deleteLocalTags(tagNames, options) {
+	if (tagNames.length === 0) return;
+	await git([
+		"tag",
+		"-d",
+		...tagNames
+	], options);
+}
 function toGitCommandError(args, cwd, cause) {
 	const exitCode = cause instanceof Error && "code" in cause && typeof cause.code === "number" ? cause.code : void 0;
 	const stderr = cause instanceof Error && "stderr" in cause && typeof cause.stderr === "string" ? cause.stderr.trim() : "";
@@ -578,6 +625,10 @@ function topologicalOrder(graph) {
 	if (pending.size > 0) throw new DependencyCycleError(findCycle(graph, new Set(pending.keys())));
 	return ordered;
 }
+/** The packages a release order names, in that order, for the stages that need each package's manifest rather than only its name. */
+function orderedPackages(graph, order) {
+	return order.map((name) => mustGet(graph.packages, name, "package"));
+}
 /**
 * Walks dependency edges between the packages Kahn's algorithm could not place, until it revisits one, so the error can name a concrete loop rather than just a set of packages. Every unplaced package is unplaced precisely because at least one of its own dependencies is too, so the walk always reaches a repeat.
 */
@@ -656,6 +707,8 @@ function matchTrailerLine(message, key) {
 }
 //#endregion
 //#region src/plugins.ts
+/** The one plugin a private package is kept off by default: see `resolveWorkspacePublishPlugins` for why a package that never reaches a registry does not get a public GitHub Release either. */
+const GITHUB_RELEASE_PLUGIN = "@semantic-release/github";
 /** semantic-release's own `getLastRelease` returns `{}` for a package with no prior tag -- not `undefined`, and not a fully-populated `LastRelease` -- contradicting the `gitHead: string` its own type declares. Narrows structurally rather than trusting that declared type, so a first-release context's `lastRelease` (correctly, at runtime) never claims a `gitHead` it does not have. */
 function hasGitHead(lastRelease) {
 	return typeof lastRelease === "object" && lastRelease !== null && "gitHead" in lastRelease && typeof lastRelease.gitHead === "string";
@@ -782,13 +835,17 @@ function resolvePublishPlugins(specs, workspaceRoot, options) {
 /**
 * Resolves the publish plugin list of every package in the workspace: the workspace-wide list for each package, except where `packagePlugins` names a package, whose own list replaces it. Every list is held to the same rules as `resolvePublishPlugins` applies to a workspace-wide one, and a failure in an override names the package it belongs to.
 *
+* A package whose manifest sets `private: true` and which no `packagePlugins` entry names gets the workspace-wide list minus `@semantic-release/github`. A private package is never published, so a public GitHub Release for it advertises something nobody can install, and that release is not merely redundant: `@semantic-release/github` sets `make_latest` from the release branch alone, with no option to opt out, so every release it creates claims the repository's Latest label and the last one created keeps it. A private package sitting at the end of the topological order (which is where a package that depends on the published ones necessarily sits) therefore takes the label on every run. Everything the private package actually needs from the run is untouched: its version bump, its tag, and the dependency cascade to its dependents all come from the other plugins and from the orchestrator itself.
+*
+* A `packagePlugins` entry naming a private package is taken exactly as written, `@semantic-release/github` included, so a workspace that does want a Release for a private package can still say so.
+*
 * A `packagePlugins` key that matches no package is rejected rather than ignored: a misspelt name would otherwise leave the package it meant on the workspace-wide list with nothing to say so, which for the intended use (keeping a package out of a step such as GitHub Release creation) is a silent wrong result.
 */
-function resolveWorkspacePublishPlugins(packageNames, specs, workspaceRoot, options) {
+function resolveWorkspacePublishPlugins(packages, specs, workspaceRoot, options) {
 	const overrides = specs.packagePlugins === void 0 ? [] : Object.entries(specs.packagePlugins);
-	const known = new Set(packageNames);
+	const known = new Set(packages.map((pkg) => pkg.name));
 	const unknown = overrides.map(([name]) => name).filter((name) => !known.has(name));
-	if (unknown.length > 0) throw new ReleaseConfigurationError(`packagePlugins names ${unknown.map((name) => `"${name}"`).join(", ")}, which ${unknown.length === 1 ? "is" : "are"} not a package in this workspace. Packages: ${packageNames.join(", ")}.`);
+	if (unknown.length > 0) throw new ReleaseConfigurationError(`packagePlugins names ${unknown.map((name) => `"${name}"`).join(", ")}, which ${unknown.length === 1 ? "is" : "are"} not a package in this workspace. Packages: ${[...known].join(", ")}.`);
 	const workspaceWide = resolvePublishPlugins(specs.plugins, workspaceRoot, options);
 	const resolvedOverrides = /* @__PURE__ */ new Map();
 	for (const [name, list] of overrides) try {
@@ -797,7 +854,9 @@ function resolveWorkspacePublishPlugins(packageNames, specs, workspaceRoot, opti
 		if (cause instanceof ReleaseConfigurationError) throw new ReleaseConfigurationError(`packagePlugins for "${name}": ${cause.message}`);
 		throw cause;
 	}
-	return new Map(packageNames.map((name) => [name, resolvedOverrides.get(name) ?? workspaceWide]));
+	const privateSpecs = specs.plugins.filter((spec) => parsePublishPluginSpec(spec)[0] !== GITHUB_RELEASE_PLUGIN);
+	const forPrivatePackages = privateSpecs.length === specs.plugins.length ? workspaceWide : resolvePublishPlugins(privateSpecs, workspaceRoot, options);
+	return new Map(packages.map((pkg) => [pkg.name, resolvedOverrides.get(pkg.name) ?? (pkg.private ? forPrivatePackages : workspaceWide)]));
 }
 /**
 * Resolves a plugin module name to an absolute file path, first from this tool's own module context (its peer dependencies, which every workspace installing the orchestrator must provide) and then from the workspace root (a workspace's own plugin dependencies, such as a custom changelog plugin). Both bases are named in the error when neither can resolve the name.
@@ -863,6 +922,27 @@ function formatTagForPackage(tagFormat, name) {
 * Why publish is not just another semantic-release() call: semantic-release's own `run()` unconditionally derives `lastRelease` from the newest tag already on the branch matching `tagFormat`, and this mode has, by the time phase 5 runs, already created and pushed that exact tag itself. A second real `semanticRelease()` call would see its own just-created tag as the already-published release and compute the wrong next version from it. Phase 5 instead calls each resolved plugin module's own exported `verifyConditions`/`publish`/`success` functions directly, with a hand-built context -- the same public per-plugin API surface semantic-release's own core calls internally, just invoked without going through the parts of `run()` that assume a not-yet-tagged repository.
 */
 async function releaseWorkspaceSingleCommit(options) {
+	const log = options.log ?? console.log;
+	const maxAttempts = resolvePushAttempts(options.pushAttempts);
+	let lastLoss;
+	for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+		const result = await attemptSingleCommitRelease(options);
+		if (result.kind === "complete") return result.outcome;
+		if (result.kind === "pushed") {
+			await result.publish();
+			return result.outcome;
+		}
+		lastLoss = result.error;
+		log(`${packageName}: attempt ${String(attempt)} of ${String(maxAttempts)} lost the push, because ${result.branch} advanced to ${result.remoteTip} before this run's own refs reached the remote. This attempt's commit and tags have been discarded; recomputing the release against the new tip.`);
+	}
+	throw new WorkspaceStateError(`${packageName}: gave up after ${String(maxAttempts)} attempt(s) to push the release, each overtaken by another commit landing on the release branch first. Nothing was published and no tag reached the remote, so re-running is safe and loses nothing. Raise "pushAttempts" if this branch is busy enough that ${String(maxAttempts)} is genuinely too few. The last push failed with: ${lastLoss === void 0 ? "unknown" : lastLoss.message}`);
+}
+function resolvePushAttempts(configured) {
+	if (configured === void 0) return 5;
+	if (!Number.isInteger(configured) || configured < 1) throw new ReleaseConfigurationError(`"pushAttempts" must be a positive integer; received ${String(configured)}.`);
+	return configured;
+}
+async function attemptSingleCommitRelease(options) {
 	const root = resolve(options.root ?? process.cwd());
 	const log = options.log ?? console.log;
 	const dryRun = options.dryRun === true;
@@ -874,7 +954,7 @@ async function releaseWorkspaceSingleCommit(options) {
 	validateDependencyRanges(graph);
 	const order = topologicalOrder(graph);
 	log(`${packageName}: ${String(order.length)} packages in release order: ${order.join(" -> ")} (commitStrategy: single)`);
-	const resolvedPlugins = resolveWorkspacePublishPlugins(order, {
+	const resolvedPlugins = resolveWorkspacePublishPlugins(orderedPackages(graph, order), {
 		plugins: options.plugins ?? SINGLE_COMMIT_DEFAULT_PUBLISH_PLUGINS,
 		packagePlugins: options.packagePlugins
 	}, workspace.root, {
@@ -946,8 +1026,11 @@ async function releaseWorkspaceSingleCommit(options) {
 		}
 	}
 	if (dryRun || planned.length === 0) return {
-		order,
-		packages: outcomes
+		kind: "complete",
+		outcome: {
+			order,
+			packages: outcomes
+		}
 	};
 	const branch = captured.branch;
 	const repositoryUrl = captured.repositoryUrl;
@@ -986,26 +1069,51 @@ async function releaseWorkspaceSingleCommit(options) {
 	const commitSha = (await git(["rev-parse", "HEAD"], { cwd: repoRoot })).trim();
 	const tagNames = planned.map((release) => release.gitTag);
 	for (const tagName of tagNames) await createTag(tagName, commitSha, { cwd: repoRoot });
-	await pushHeadAndTags(tagNames, { cwd: repoRoot });
-	log(`${packageName}: committed ${commitSha} and pushed ${String(tagNames.length)} tag(s): ${tagNames.join(", ")}`);
-	for (const release of planned) {
-		const releases = [];
-		for (const [modulePath, pluginConfig] of mustGet(resolvedPlugins, release.pkg.name, "publish plugins")) {
-			const plugin = await loadReleasePlugin(modulePath, moduleCache);
-			if (plugin.publish) {
-				const result = await plugin.publish(pluginConfig, buildPluginContext(release, shared, capturedCommits, releases));
-				if (result !== false && result !== void 0) releases.push(result);
-			}
-		}
-		for (const [modulePath, pluginConfig] of mustGet(resolvedPlugins, release.pkg.name, "publish plugins")) {
-			const plugin = await loadReleasePlugin(modulePath, moduleCache);
-			if (plugin.success) await plugin.success(pluginConfig, buildPluginContext(release, shared, capturedCommits, releases));
+	const branchName = await currentBranch({ cwd: repoRoot });
+	try {
+		await pushHeadAndTags(tagNames, { cwd: repoRoot });
+	} catch (error) {
+		if (!(error instanceof GitCommandError)) throw error;
+		let remoteTip;
+		try {
+			remoteTip = await fetchBranchTip(branchName, { cwd: repoRoot });
+		} catch {
+			throw error;
 		}
-		log(`${release.pkg.name}: published ${release.gitTag}`);
+		if (await isAncestor(remoteTip, "HEAD", { cwd: repoRoot })) throw error;
+		await deleteLocalTags(tagNames, { cwd: repoRoot });
+		await resetHardTo(remoteTip, { cwd: repoRoot });
+		return {
+			kind: "lost",
+			error,
+			branch: branchName,
+			remoteTip
+		};
 	}
+	log(`${packageName}: committed ${commitSha} and pushed ${String(tagNames.length)} tag(s): ${tagNames.join(", ")}`);
 	return {
-		order,
-		packages: outcomes
+		kind: "pushed",
+		outcome: {
+			order,
+			packages: outcomes
+		},
+		publish: async () => {
+			for (const release of planned) {
+				const releases = [];
+				for (const [modulePath, pluginConfig] of mustGet(resolvedPlugins, release.pkg.name, "publish plugins")) {
+					const plugin = await loadReleasePlugin(modulePath, moduleCache);
+					if (plugin.publish) {
+						const result = await plugin.publish(pluginConfig, buildPluginContext(release, shared, capturedCommits, releases));
+						if (result !== false && result !== void 0) releases.push(result);
+					}
+				}
+				for (const [modulePath, pluginConfig] of mustGet(resolvedPlugins, release.pkg.name, "publish plugins")) {
+					const plugin = await loadReleasePlugin(modulePath, moduleCache);
+					if (plugin.success) await plugin.success(pluginConfig, buildPluginContext(release, shared, capturedCommits, releases));
+				}
+				log(`${release.pkg.name}: published ${release.gitTag}`);
+			}
+		}
 	};
 }
 /**
@@ -1151,7 +1259,7 @@ async function detachWorkspaceRelease(options) {
 	validateDependencyRanges(graph);
 	const order = topologicalOrder(graph);
 	log(`${packageName}: ${String(order.length)} packages in release order (gated -- tag only, publish deferred): ${order.join(" -> ")}`);
-	const publishPlugins = resolveWorkspacePublishPlugins(order, {
+	const publishPlugins = resolveWorkspacePublishPlugins(orderedPackages(graph, order), {
 		plugins: options.plugins ?? DEFAULT_PUBLISH_PLUGINS,
 		packagePlugins: options.packagePlugins
 	}, workspace.root, { requireGitPlugin: !dryRun });
@@ -1293,7 +1401,7 @@ async function releaseWorkspace(options = {}) {
 	validateDependencyRanges(graph);
 	const order = topologicalOrder(graph);
 	log(`${packageName}: ${String(order.length)} packages in release order: ${order.join(" -> ")}`);
-	const publishPlugins = resolveWorkspacePublishPlugins(order, {
+	const publishPlugins = resolveWorkspacePublishPlugins(orderedPackages(graph, order), {
 		plugins: options.plugins ?? DEFAULT_PUBLISH_PLUGINS,
 		packagePlugins: options.packagePlugins
 	}, workspace.root, { requireGitPlugin: !dryRun });
@@ -1446,4 +1554,4 @@ async function bumpDependents(released, version, graph, options) {
 	return applied;
 }
 //#endregion
-export { DEFAULT_PUBLISH_PLUGINS, DependencyCycleError, GitCommandError, ReleaseConfigurationError, SINGLE_COMMIT_DEFAULT_PUBLISH_PLUGINS, UnsupportedDependencyRangeError, WorkspaceDiscoveryError, WorkspaceReleaseError, WorkspaceStateError, buildDependencyGraph, classifyDependencyRange, createScopedPlugins, discoverWorkspace, filterCommitsToDirectory, packageName, readManifest, releaseWorkspace, resolvePublishPlugins, resolveWorkspacePublishPlugins, resumeWorkspaceRelease, topologicalOrder, updateDependencyRange, writeDependencyRange };
+export { DEFAULT_PUBLISH_PLUGINS, DependencyCycleError, GitCommandError, ReleaseConfigurationError, SINGLE_COMMIT_DEFAULT_PUBLISH_PLUGINS, UnsupportedDependencyRangeError, WorkspaceDiscoveryError, WorkspaceReleaseError, WorkspaceStateError, buildDependencyGraph, classifyDependencyRange, createScopedPlugins, discoverWorkspace, filterCommitsToDirectory, orderedPackages, packageName, readManifest, releaseWorkspace, resolvePublishPlugins, resolveWorkspacePublishPlugins, resumeWorkspaceRelease, topologicalOrder, updateDependencyRange, writeDependencyRange };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exadev/semantic-release-workspace",
-  "version": "2.2.0",
+  "version": "3.0.1",
   "description": "Independent per-package semantic-release orchestration for pnpm workspaces, without lockstep versioning.",
   "type": "module",
   "repository": {