Releasepr

---
name: releasepr
description: "Guides adoption and day-to-day use of the pr-release CLI in a consuming GitHub repository: installing the binary, wiring the release GitHub Actions workflow, authoring .pr-release.yaml, following conventional commits for semantic versioning, adding custom release notes with add-note, validating with dry-run, and understanding the release-PR then merge then production-release lifecycle. Use when a project depends on compozy/releasepr (pr-release) and needs to configure, run, or troubleshoot its release automation. Not for editing the pr-release Go source itself, and not a general changelog or semantic-versioning tutorial."
license: MIT
metadata:
  domain: release-automation
  triggers: pr-release, releasepr, release PR, changelog, conventional commits, git-cliff, GoReleaser, .pr-release.yaml, add-note, dry-run
  role: specialist
  scope: integration
---

`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`                                      |
| 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`, `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`,
   `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.