Release: fix release-plz PR creation before the clean 1.0 release cut

[joeldsouzax]

When

After API-freeze hardening is complete — as part of cutting a clean 1.0 release. Not now: this does not block feature development, and the real code gate (Nix Flake Check) is green on every merge. Deferred deliberately.

Problem

The Release workflow (release-plz) has failed on every push to main for a long time — confirmed back to at least 2026-06-18 (saga #127, $all #216, is_conflict #200, and both export/import merges #218/#219). It is not caused by any of those changes; it is a repo/token configuration issue.

Failure (identical each run):

ERROR Failed to open PR
  message: "GitHub Actions is not permitted to create or approve pull requests." (HTTP 403)
  POST https://api.github.com/repos/devrandom-labs/nexus/pulls

Root cause — the repo's Actions permissions block release-plz from opening its release PR:

$ gh api repos/devrandom-labs/nexus/actions/permissions/workflow
{ "default_workflow_permissions": "read", "can_approve_pull_request_reviews": false }

Fix options (pick one when cutting 1.0)

1. Dedicated PAT / GitHub App token for release-plz (recommended — release-plz's documented setup; keeps the default GITHUB_TOKEN read-only). Store as a secret and pass it to the release-plz action.
2. Loosen the default token — Settings → Actions → General → Workflow permissions → "Read and write" + enable "Allow GitHub Actions to create and approve pull requests". Equivalent API call:

   gh api -X PUT repos/devrandom-labs/nexus/actions/permissions/workflow \
     -f default_workflow_permissions=write -F can_approve_pull_request_reviews=true
   

Definition of done

• A push to main produces a green Release run that opens/updates the release PR.
• The 1.0 release is cut cleanly (versions, changelog, tags) with no manual workarounds.

Tracks release mechanics only — no library code change expected.

🤖 Generated with Claude Code