fix: harden publish for trusted publishing + stranded tags (#101)

## Summary

Two related fixes for publish failures hit when releasing brand-new
packages from GitHub Actions with npm trusted publishing (OIDC).
Reported by a downstream project (varlock) where publishing
`@varlock/kubernetes-plugin@0.1.0` failed because the package didn't
exist on npm yet, leaving a stranded GH draft release + remote tag that
then broke the retry's `git push --tags`.

### 1. Detect new-package + OIDC-only auth before any side effects

Trusted publishing can't bootstrap a package that doesn't exist on npm —
the trusted publisher config has to be created on npmjs.com first, which
requires the package to already exist. We now check the registry up
front and emit a specific, actionable error directing the user to
publish a `0.0.0` placeholder first.

The check is gated on `willUseOidcExclusively` (OIDC env detected AND no
`NPM_TOKEN`/`NODE_AUTH_TOKEN` AND no `.npmrc` auth) to avoid false
positives for users who enable `id-token: write` for provenance
attestations alongside token auth. Runs before `gh release create` and
`npm publish`, so a failing check leaves no stranded state. On
`--dry-run` it warns instead of erroring.

### 2. Per-tag force push replaces blanket `git push --tags`

`gh release create --draft --target SHA` creates the tag on the remote
at draft-creation time. If a prior publish failed and HEAD has since
moved, the remote tag is stale and `git push --tags` rejects with
"already exists". The fix iterates `releasePlan.releases` minus
`result.failed` and force-pushes each tag individually.

Preserves the existing anySucceeded-aware semantics used for local tag
movement: packages whose targets all succeeded in a prior run are
stripped upstream by the `alreadyPublished` filter, so their tags stay
at the SHA the artifact was actually published from — the GitHub release
continues to point at the right commit. Mixed-success scenarios (e.g.
package A published from SHA1 in run 1, package B retried from SHA2 in
run 2) end up correct: A's tag is left at SHA1, only B's tag is
force-pushed to SHA2.

## Test plan

- [x] `bun run check` passes (lint + format + typecheck)
- [x] `bun run test` — 258/258 pass
- [ ] Verify in downstream project (varlock) that the new error fires on
the OIDC + new-package case
- [ ] Verify a clean retry after publishing a `0.0.0` placeholder
succeeds and pushes tags without rejection

---------

Co-authored-by: CI <ci@example.com>

Author: theoephraim

.bumpy/publish-oidc-and-tag-push.md

@@ -0,0 +1,8 @@
+---
+'@varlock/bumpy': patch
+---
+
+Harden the publish flow for two failure modes hit when releasing brand-new packages via GitHub Actions + npm trusted publishing (OIDC).
+
+- Detect the new-package case before any side effects. When OIDC is the only available auth path (no `NPM_TOKEN`/`NODE_AUTH_TOKEN`, no `.npmrc` auth), bumpy now checks the npm registry up front and emits a clear error directing the user to publish a `0.0.0` placeholder before merging — instead of failing partway through with stranded GitHub draft releases and remote tags. The check is skipped when a token fallback is present, so users who enable `id-token: write` for provenance attestations alongside token auth are unaffected.
+- Replace blanket `git push --tags` after publish with per-tag force push. `gh release create --draft --target SHA` creates the tag on the remote at draft-creation time; if a prior publish failed and HEAD has since moved, the remote tag is stale and `git push --tags` rejects with "already exists". The new logic iterates `releasePlan.releases` minus failed packages and force-pushes each tag individually, preserving the anySucceeded-aware semantics already used for local tag movement — packages whose targets all succeeded in a prior run are stripped upstream and their tags stay at the SHA the artifact was actually published from.

packages/bumpy/src/commands/publish.ts

@@ -2,8 +2,8 @@ import { log, colorize } from '../utils/logger.ts';
 import { loadConfig } from '../core/config.ts';
 import { discoverWorkspace } from '../core/workspace.ts';
 import { DependencyGraph } from '../core/dep-graph.ts';
-import { pushWithTags, hasUncommittedChanges } from '../core/git.ts';
-import { publishPackages } from '../core/publish-pipeline.ts';
+import { forcePushTag, hasUncommittedChanges, tagExists } from '../core/git.ts';
+import { publishPackages, willUseOidcExclusively } from '../core/publish-pipeline.ts';
 import {
   createIndividualReleases,
   findReleaseByTag,
@@ -24,7 +24,7 @@ import {
 import { loadFormatter } from '../core/changelog.ts';
 import { detectWorkspaces } from '../utils/package-manager.ts';
 import { CI_PLAN_CACHE_PATH } from './ci.ts';
-import { tryRunArgs } from '../utils/shell.ts';
+import { runArgsAsync, tryRunArgs } from '../utils/shell.ts';
 import type { BumpyConfig, PackageConfig, ReleasePlan, PlannedRelease, WorkspacePackage } from '../types.ts';
 
 interface PublishCommandOptions {
@@ -108,6 +108,22 @@ export async function publishCommand(rootDir: string, opts: PublishCommandOption
   }
   console.log();
 
+  // Trusted publishing (OIDC) cannot bootstrap a new package — fail early if any
+  // package being published doesn't exist on npm yet, before we create draft releases.
+  // Only checks when OIDC is the only available auth (no token fallback), to avoid
+  // false positives for users with id-token: write enabled solely for provenance.
+  if (willUseOidcExclusively(rootDir)) {
+    const newPackages = await findPackagesMissingFromNpm(toPublish, packages);
+    if (newPackages.length > 0) {
+      const logFn = opts.dryRun ? log.warn : log.error;
+      logFn(`Trusted publishing (OIDC) cannot create a new package. The following don't exist on npm yet:`);
+      for (const name of newPackages) logFn(`  • ${name}`);
+      logFn(`Publish a 0.0.0 placeholder version manually to claim the name, then configure`);
+      logFn(`trusted publishing on npmjs.com. Bumpy will then publish the real version via OIDC.`);
+      if (!opts.dryRun) process.exit(1);
+    }
+  }
+
   // Load the changelog formatter for release note generation
   const formatter = config.changelog !== false ? await loadFormatter(config.changelog, rootDir) : undefined;
   const ghAvailable = isGhAvailable();
@@ -316,15 +332,37 @@ export async function publishCommand(rootDir: string, opts: PublishCommandOption
     process.exit(1);
   }
 
-  // Push tags
+  // Push tags — per-tag force push only for releases handled this run.
+  //
+  // We use `releasePlan.releases` (not result.published) so that packages with
+  // skipNpmPublish or private packages with `privatePackages.tag` enabled are
+  // covered too — their local tags are created in publish-pipeline regardless of
+  // whether npm publish ran. Failed packages are skipped (their local tag was
+  // not created). The `alreadyPublished` filter above has already stripped
+  // packages whose targets all succeeded in prior runs, so we never touch tags
+  // tied to a previously-published SHA.
+  //
+  // Force-push is necessary because `gh release create --draft --target SHA`
+  // creates the tag on the remote at draft-creation time. If a previous attempt
+  // failed and HEAD has since moved, the remote tag is at a stale SHA and a
+  // plain `git push --tags` would reject. Force is safe here because the local
+  // tag was just created at the SHA we successfully published from.
   if (!opts.dryRun && !opts.noPush && result.published.length > 0) {
-    try {
-      log.step('Pushing tags...');
-      pushWithTags({ cwd: rootDir });
-      log.success('Pushed tags to remote');
-    } catch (err) {
-      log.warn(`Failed to push tags: ${err instanceof Error ? err.message : err}`);
+    const failed = new Set(result.failed.map((f) => f.name));
+    const pushed: string[] = [];
+    log.step('Pushing tags...');
+    for (const release of releasePlan.releases) {
+      if (failed.has(release.name)) continue;
+      const tag = `${release.name}@${release.newVersion}`;
+      if (!tagExists(tag, { cwd: rootDir })) continue;
+      try {
+        forcePushTag(tag, { cwd: rootDir });
+        pushed.push(tag);
+      } catch (err) {
+        log.warn(`  Failed to push tag ${tag}: ${err instanceof Error ? err.message : err}`);
+      }
     }
+    if (pushed.length > 0) log.success(`Pushed ${pushed.length} tag(s) to remote`);
   }
 
   // Fallback: if gh isn't available, we can't use draft releases — use legacy individual releases
@@ -478,3 +516,40 @@ async function checkIfPublished(name: string, version: string, pkgConfig?: Packa
     return false;
   }
 }
+
+/**
+ * Check whether a package exists on npm at all (any version).
+ * Returns true if the package is registered, false if it doesn't exist or the query fails.
+ */
+async function packageExistsOnNpm(name: string, registry?: string): Promise<boolean> {
+  const args = ['npm', 'info', name, 'name'];
+  if (registry) args.push('--registry', registry);
+  try {
+    const result = await runArgsAsync(args);
+    return result.trim() === name;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Filter `toPublish` to package names that don't exist on npm yet.
+ * Skips packages not going through the standard npm publish flow.
+ */
+async function findPackagesMissingFromNpm(
+  toPublish: PlannedRelease[],
+  packages: Map<string, WorkspacePackage>,
+): Promise<string[]> {
+  const missing: string[] = [];
+  await Promise.all(
+    toPublish.map(async (release) => {
+      const pkg = packages.get(release.name)!;
+      const pkgConfig = pkg.bumpy || {};
+      if (pkgConfig.publishCommand || pkgConfig.skipNpmPublish) return;
+      if (pkg.private && !pkgConfig.publishCommand) return;
+      const exists = await packageExistsOnNpm(release.name, pkgConfig.registry);
+      if (!exists) missing.push(release.name);
+    }),
+  );
+  return missing;
+}

packages/bumpy/src/core/git.ts

@@ -16,6 +16,21 @@ export function pushWithTags(opts?: { cwd?: string }): void {
   });
 }
 
+/**
+ * Force-push a single tag to origin, using BUMPY_GH_TOKEN if available.
+ *
+ * Force is required because `gh release create --draft --target SHA` creates
+ * the tag on the remote at draft-creation time. If a previous publish attempt
+ * failed and HEAD has since moved, the remote tag points at the stale SHA —
+ * `git push --tags` would reject. The caller is responsible for ensuring the
+ * local tag is at the correct SHA (i.e. only call after a successful publish).
+ */
+export function forcePushTag(tag: string, opts?: { cwd?: string }): void {
+  withGitToken(opts?.cwd, () => {
+    runArgs(['git', 'push', 'origin', `refs/tags/${tag}`, '--force'], opts);
+  });
+}
+
 /**
  * Temporarily configure git credentials using BUMPY_GH_TOKEN (or GH_TOKEN),
  * execute a callback, then restore the original config.

packages/bumpy/src/core/publish-pipeline.ts

@@ -30,13 +30,30 @@ export interface PublishResult {
  * - GitLab CI: `GITLAB_CI` + `NPM_ID_TOKEN`
  * - CircleCI: `CIRCLECI` + `NPM_ID_TOKEN`
  */
-function detectOidcProvider(): 'github-actions' | 'gitlab' | 'circleci' | null {
+export function detectOidcProvider(): 'github-actions' | 'gitlab' | 'circleci' | null {
   if (process.env.ACTIONS_ID_TOKEN_REQUEST_URL) return 'github-actions';
   if (process.env.GITLAB_CI && process.env.NPM_ID_TOKEN) return 'gitlab';
   if (process.env.CIRCLECI && process.env.NPM_ID_TOKEN) return 'circleci';
   return null;
 }
 
+/**
+ * Returns true when OIDC trusted publishing is the only available npm auth path:
+ * an OIDC provider is detected AND no token env vars or .npmrc auth are present.
+ *
+ * Used to gate checks that only matter when OIDC will definitely be used — e.g.
+ * erroring when a brand-new package can't be bootstrapped via trusted publishing.
+ * Detection alone is leaky (id-token: write is also set for provenance), so this
+ * helper avoids false positives when a token fallback exists.
+ */
+export function willUseOidcExclusively(rootDir: string): boolean {
+  if (!detectOidcProvider()) return false;
+  if (process.env.NPM_TOKEN || process.env.NODE_AUTH_TOKEN) return false;
+  const npmrcPath = resolve(rootDir, '.npmrc');
+  const existingNpmrc = existsSync(npmrcPath) ? readFileSync(npmrcPath, 'utf-8') : '';
+  return !existingNpmrc.includes(':_authToken=');
+}
+
 const OIDC_NPM_UPGRADE_HINTS: Record<string, string> = {
   'github-actions': 'Add `actions/setup-node@v6` with `node-version: lts/*` to your workflow',
   gitlab: 'Use a Node.js image with npm >= 11.5.1 or run `npm install -g npm@latest`',