[PAMulligan]

Description

The first run of the two-stage Release workflow (v2.1.0, run 40541920352) bumped the three version files, wrote the changelog, pushed release/v2.1.0 and then failed red at Open release PR:

pull request create failed: GraphQL: GitHub Actions is not permitted to create or approve pull requests (createPullRequest)

The repository setting behind it (Settings > Actions > General > Workflow permissions > "Allow GitHub Actions to create and approve pull requests") is off and there is no RELEASE_TOKEN secret, so the step fell back to GITHUB_TOKEN, which cannot open a pull request at all in that state. The workflow header, the step's notice and the CONTRIBUTING.md callout all assumed GITHUB_TOKEN could open the PR and would only fail to start CI, so "close and reopen" was advice for a PR that never existed. #143 was opened by hand from the pushed branch.

This is option 3 from the issue, which applies whichever permanent fix is chosen:

• release.yml, "Open release PR" step. When gh pr create fails, the branch is already pushed, so the step exits 0 with a ::warning:: and writes to the step summary: the error verbatim, the compare link with the title prefilled, and a ready-to-paste gh pr create … --body-file - <<'PR_BODY' command carrying the PR body the workflow would have used (RELEASE_NOTES.md is gitignored, so the summary is the only copy of it). When the error is the Actions permission, the summary also names both permanent fixes. The success and existing-PR paths are unchanged apart from writing the body under RUNNER_TEMP.
• Workflow header and CONTRIBUTING.md callout now describe the three states: RELEASE_TOKEN present (PR opened as that user, CI runs by itself), GITHUB_TOKEN with the setting on (PR opens, close and reopen once for CI), GITHUB_TOKEN with the setting off (hand-off through the step summary).
• scripts/__tests__/release-workflow.test.js now extracts the step's run: | script from the YAML and executes it against a stub gh: success, an existing PR refreshed rather than duplicated, the CI notice only without RELEASE_TOKEN, refusal by the Actions permission (exit 0, warning, compare link, command, body, both fixes named), and any other failure (same hand-off, no permission advice). It also asserts the script takes every input from env: and never from a ${{ }} expression.

Step summary as written when the PR is refused (stub run)

Release PR not opened

Branch release/v2.2.0 is pushed, but gh pr create failed:

pull request create failed: GraphQL: GitHub Actions is not permitted to create or approve pull requests (createPullRequest)

The step ran with GITHUB_TOKEN and the repository setting Allow GitHub Actions to create and approve pull requests (Settings > Actions > General > Workflow permissions) is off. To let the workflow open the PR itself next time, either add a RELEASE_TOKEN repository secret (fine-grained PAT with Contents and Pull requests: write; the PR is then opened as that user and CI starts on its own) or turn that setting on (the PR then still needs one close and reopen before CI runs).

Open the PR by hand from the compare view, pasting the body below, or with the GitHub CLI:

gh pr create --repo PMDevSolutions/Aurelius --base main --head release/v2.2.0 \
  --title "chore(release): v2.2.0" --body-file - <<'PR_BODY'
Release **v2.2.0** prepared by the Release workflow (`auto` bump).

Merging this PR tags the merge commit as `v2.2.0` and publishes the GitHub Release automatically.

## Release notes

### Features

* **gui:** a feature ([abc1234](https://github.com/PMDevSolutions/Aurelius/commit/abc1234))


### Bug Fixes

* **ci:** a fix ([def5678](https://github.com/PMDevSolutions/Aurelius/commit/def5678))
PR_BODY

Not done here, both need the repository owner: a fine-grained PAT stored as RELEASE_TOKEN (the better option: the PR is opened as that user and CI runs on it by itself), or turning the setting on. For an organization-owned repository the setting is inherited from the organization, and reading the PMDevSolutions value needs the admin:org scope that the gh login on this machine lacks, so it may have to be enabled there first:

gh api -X PUT orgs/PMDevSolutions/actions/permissions/workflow \
  -f default_workflow_permissions=read -F can_approve_pull_request_reviews=true
gh api -X PUT repos/PMDevSolutions/Aurelius/actions/permissions/workflow \
  -f default_workflow_permissions=read -F can_approve_pull_request_reviews=true

After that the workflow opens the PR itself, but it still needs one close and reopen before CI starts.

Related Issue

Closes #144. Refs #139, #143.

Type of Change

• Bug fix (non-breaking change that fixes an issue)
• New feature (non-breaking change that adds functionality)
• Documentation update
• Chore (dependency updates, CI changes, refactoring)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)

Checklist

• Tests pass (pnpm vitest run --config scripts/__tests__/vitest.config.js scripts/__tests__/)
• Linting passes (./scripts/lint-and-format.sh --check)
• Types check (pnpm tsc --noEmit): not applicable, no TypeScript changed
• Documentation updated (CONTRIBUTING.md, the release.yml header)

🤖 Generated with Claude Code