releasepr

pr-release (Go module github.com/compozy/releasepr) automates the GitHub release workflow: it inspects conventional commits, computes the next semantic version, generates a git-cliff changelog, opens or updates a release pull request, and — once that PR merges — drives a GoReleaser production release. This skill is for agents working in a consuming project that depends on pr-release. It is not for hacking on the pr-release Go source.

The detail that makes setup and usage correct lives in references/. The inline content in this file is a dispatcher and a tripwire, not the contract. Match the task in the router, then read the listed file in full before acting.

Required Reading Router

Match the task to the row. Read the listed file(s) in full before producing output or running commands. They are load-bearing, not appendices.

Task	MUST read
Set up pr-release in a repo for the first time	references/setup.md + references/configuration.md
Create or change .pr-release.yaml / env vars / artifacts	references/configuration.md
Run or script a CLI command, choose flags	references/commands.md
Understand or debug the release lifecycle / CI behavior	references/release-workflow.md
Write commit messages or add custom release notes	references/release-notes.md
Correct notes for an already-published release	references/published-release-repair.md + references/release-workflow.md
A release step failed or behaved unexpectedly	references/troubleshooting.md

Reference Index

• references/setup.md — install options (prebuilt tarball, go install), the GitHub token requirement, owner/repo auto-detection order, copying the workflow template, and the first dry-run.
• references/configuration.md — every .pr-release.yaml field, defaults, validation rules, the full environment-variable alias matrix, and release_artifacts constraints.
• references/commands.md — pr-release, plan, release-body, dry-run, add-note, version: every flag and its exact behavior.
• references/release-workflow.md — the end-to-end lifecycle: which commits trigger what, release branch/PR naming, dry-run checks, and how a merge becomes a production release.
• references/release-notes.md — conventional-commit prefixes that drive the version bump, the add-note workflow, and .release-notes/ archival.
• references/troubleshooting.md — symptom → cause → fix for the common failures (token format, owner/repo detection, "no release PR produced", etc.).

Operating loop

1. Confirm the dependency. Verify the project actually uses pr-release (a release workflow invoking pr-release, a .pr-release.yaml, or an explicit request). If it does not, this skill does not apply.

2. Verify wiring before changing anything. Run the read-only helper from the consuming repo root: bash skills/releasepr/scripts/check-setup.sh It reports PASS/WARN/FAIL for the binary, token, config file, owner/repo resolution, conventional commits, and the workflow file. It only inspects — it never writes, pushes, or calls mutating APIs.

3. Set up (if check-setup reports missing pieces). Copy skills/releasepr/assets/release.yml.template into .github/workflows/ and skills/releasepr/assets/pr-release.yaml.template to .pr-release.yaml, then adjust. STOP. Read references/setup.md and references/configuration.md in full before installing pr-release or editing any config. The asset templates and the bullets here are starting points, not the contract — defaults, validation ranges, and the env-var matrix are only complete in those files.

4. Run or script a command. The de-facto standard CI invocation across every observed consumer is pr-release pr-release --force --enable-rollback --ci-output — install via go run "<module>@<pinned tag>". --force makes it idempotent, not "release with no changes". STOP. Read references/commands.md in full before running pr-release, plan, release-body, dry-run, or add-note, or adding any flag to a script. The flag list here is a tripwire; semantics (e.g. --rollback, --session-id, --skip-pr) are only correct in that file.

5. Reason about lifecycle / CI. Before explaining why a release did or did not happen, or editing the workflow. STOP. Read references/release-workflow.md in full before diagnosing CI behavior or modifying the release workflow. Trigger rules and the merge → production-release path are only accurate there.

6. Diagnose a failure. STOP. Read references/troubleshooting.md in full before proposing a fix for any pr-release error. Match the exact error string to its row.

Gist tripwires (incomplete on purpose)

Conventional-commit prefixes drive the version bump — wrong prefixes mean wrong versions or "no changes":

• fix: → patch · feat: → minor · feat!: / BREAKING CHANGE: → major.
• A commit subject starting with release: or ci(release): merged to the default branch is what triggers the production release — do not hand-write such commits.
• Bot commits and Merge pull request commits are skipped by the release-PR job.

STOP. Read references/release-notes.md and references/release-workflow.md in full before advising on commit messages or release timing. The three bullets above are tripwires, not the rule set.

Setup prerequisites that cause the most real-world failures:

• Checkout MUST be unshallow with tags (fetch-depth: 0, fetch-tags: true) or the version is wrong.
• git-cliff MUST be installed in the runner; pr-release shells out to it.
• Use a dedicated RELEASE_TOKEN (PAT/App), not the default GITHUB_TOKEN, or downstream checks won't dispatch.

STOP. Read references/setup.md in full before installing or wiring pr-release in any repository. These three are tripwires, not the setup contract.

Bundled resources

• scripts/check-setup.sh — read-only consumer-repo wiring verifier. Safe to run anytime; performs no writes, pushes, or mutating API calls.
• assets/pr-release.yaml.template — copy-in starter config (every field commented).
• assets/release.yml.template — copy-in starter GitHub Actions release workflow for a consuming repo.