fix(release): authenticate stable tag push

[kattsushi]

Closes #268

Summary

• Authenticate stable FINALIZE's atomic exact-refspec tag push with a one-shot GitHub-scoped Basic extraheader derived from the step-scoped GITHUB_TOKEN.
• Keep every checkout credential non-persisted and preserve the existing stable job permission topology.
• Add fail-closed coverage for missing/unsafe tokens, credential non-persistence, atomicity, response-loss reconciliation, and token leakage.

Failure Evidence

Exact-current PREFLIGHT passed: https://github.com/devx-op/effectify/actions/runs/33383620259

FINALIZE then failed before any public mutation: https://github.com/devx-op/effectify/actions/runs/33383831937

remote tag postverification failed for @effectify/hatchet@0.2.0

All seven stable tags, GitHub Releases, npm versions, and latest updates remained absent. The finalizer's checkout intentionally used persist-credentials: false, but its git push --atomic had no explicit authentication.

Changes

File	Change
scripts/release-finalize-stable.mjs	Validate GITHUB_TOKEN before tag mutation and apply one-shot Basic auth only to the atomic push.
scripts/release-finalize-stable.test.mjs	Cover authenticated exact refspecs, non-persistence/leakage, and missing/unsafe auth.
scripts/release-policy-contract.test.mjs	Protect auth derivation, ordering, atomicity, and documentation.
.github/SETUP.md	Document the bounded tag-push credential path.

Test Plan

• RED: finalizer suite — 89 passed, 4 failed on the missing authentication contract.
• GREEN: node --test scripts/release-finalize-stable.test.mjs — 93 passed, 0 failed.
• node --test scripts/release-policy-contract.test.mjs — 30 passed, 0 failed.
• Independent verification repeated both suites and git diff --check successfully.
• Confirmed PREFLIGHT/historical replay remain read-only and checkout/permission topology is unchanged.

Contributor Checklist

• Linked approved issue fix: complete Effect v4 cleanup and restore stable releases #268.
• Added exactly one type:* label: type:bug.
• Conventional commit; no co-author trailers.
• No tag, Release, or npm publication occurs in this PR.
• After merge, the unfinalized stable artifact will be recovered through the documented protected revert and regenerated before FINALIZE.

Summary by CodeRabbit

• Bug Fixes

  • Stable release tag pushes now authenticate securely using the release token.
  • Invalid or unsafe tokens are rejected before any local tag changes occur.
  • Authentication details are not persisted or exposed in logs.

• Documentation

  • Updated stable-release guidance to describe the secure, one-time authentication behavior.

• Tests

  • Added coverage for authenticated atomic pushes, token validation, failure handling, and credential-leak prevention.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 5c0e3168-9e58-4992-a5fe-34c0bfff8493

📥 Commits

Reviewing files that changed from the base of the PR and between 0fc672a and c7a47d2.

📒 Files selected for processing (4)

• .github/SETUP.md
• scripts/release-finalize-stable.mjs
• scripts/release-finalize-stable.test.mjs
• scripts/release-policy-contract.test.mjs

Included review availability: Your plan provides up to 1 included review per hour; 0 remain after this review.

---

📝 Walkthrough

Walkthrough

FINALIZE now validates GITHUB_TOKEN and uses a temporary GitHub-scoped Basic-auth header for atomic tag pushes. Tests verify credential handling, failure-before-mutation behavior, and policy ordering. Setup documentation describes the non-persisted authentication flow.

Changes

Stable tag authentication

Layer / File(s)	Summary
Tag push authentication scripts/release-finalize-stable.mjs	FINALIZE validates GITHUB_TOKEN, builds the Basic credential, and passes it through one-shot git -c configuration during atomic tag pushes.
Authentication regression coverage scripts/release-finalize-stable.test.mjs	Tests verify GitHub-scoped authentication, no persistent configuration, no literal token exposure, exact tag publication, and failure before mutations.
Release policy and documentation scripts/release-policy-contract.test.mjs, .github/SETUP.md	Contract tests enforce validation, credential construction, push ordering, atomic behavior, and documentation requirements. Setup instructions describe the one-shot authenticated push.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Merge Risk: 🔵 Low · up to c7a47

The change enables the stable release job to push validated tags using a narrowly scoped token without persisting checkout credentials. It is mergeable with owner awareness that the stable-release environment’s required approval controls should be confirmed before relying on its contents:write authority.

Sequence Diagram(s)

sequenceDiagram
  participant FINALIZE
  participant Git
  participant GitHub
  FINALIZE->>FINALIZE: Validate GITHUB_TOKEN
  FINALIZE->>Git: Run atomic push with one-shot extraheader
  Git->>GitHub: Push tag refs with Basic authentication
  GitHub-->>Git: Accept or reject tag push

Loading

Poem

I’m a rabbit guarding tags tonight
A tiny token makes the push just right
One-shot headers leave no trace
Bad credentials stop the race
Atomic hops reach GitHub’s gate
Clean paws celebrate the release state

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (2 warnings)

Check name	Status	Explanation	Resolution
Linked Issues check	⚠️ Warning	The PR addresses the linked issue's stable FINALIZE authentication, fail-closed behavior, publication safeguards, and regression coverage requirements [#268]. However, the provided changes do not show…	Include or provide evidence for the stable PREPARE and FINALIZE target-derivation changes required by issue #268, or link the PR to a narrower child issue if those changes are intentionally handled elsewhere.
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 4 functions across 3 files. (1 skipped: 1 …	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: authenticating the stable tag push.
Out of Scope Changes check	✅ Passed	The code, tests, policy contracts, and documentation changes all support authenticated stable tag pushing and its safeguards. No unrelated changes are shown.

Full details: Linked Issues check

Explanation

The PR addresses the linked issue's stable FINALIZE authentication, fail-closed behavior, publication safeguards, and regression coverage requirements [#268]. However, the provided changes do not show the required generalization of stable PREPARE and FINALIZE to derive package and version targets dynamically.

Full details: Docstring Coverage

Explanation

Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 4 functions across 3 files. (1 skipped: 1 unsupported.)

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/stable-finalize-tag-auth

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}