fix: fix set-commits --auto, document release workflow pitfalls

[BYK]

Summary

Fixes set-commits --auto to properly discover commits and documents release workflow pitfalls learned from shipping the sentry-release CI workflow.

Continuation of #643, #645, #648, #649 (all merged).

Changes

set-commits --auto rewrite (src/lib/api/releases.ts)

• Replace bogus {repository: "auto", commit: "auto"} — list org repos via paginated API, match against local git remote, send real refs with HEAD SHA
• Fetch previous release commit via /previous-with-commits/ endpoint so Sentry can compute the commit range (without this, 0 commits are reported)
• Paginate through all org repos with early-exit (listRepositoriesPaginated)
• Use ApiError for no-repos (correct negative caching), ValidationError for local git failures
• Fix ApiError constructor: endpoint as 4th arg, not 3rd

Fallback fix (src/commands/release/set-commits.ts)

• Catch ValidationError in setCommitsDefault → fall back to local git history

Workflow fixes (.github/workflows/sentry-release.yml)

• actions/checkout@v6 with fetch-depth: 0 (needed for --auto git discovery)
• Move --url from release create to release deploy (URL belongs on the deploy)
• Inline comments documenting every pitfall (Node.js version, env scoping, org prefix)

Documentation

• agent-guidance.md: New "Release Workflow" section with CI/CD setup notes; new Common Mistakes for version mismatch and --auto without checkout
• release.md: CI workflow example + "Important Notes" section
• create.ts help: Clarifies org/version positional format and version matching
• set-commits.ts help: Clarifies --auto requires git checkout; documents default fallback behavior
• Regenerated SKILL.md + reference files

Tests

• Isolated tests: repo discovery, pagination, no-match, no-repos, no-remote, previous commit fetch
• Command tests: --auto cwd pass-through, ValidationError fallback in default mode
• Patch coverage: releases.ts ~99%, set-commits.ts ~75%

[github-actions]

Semver Impact of This PR

🟢 Patch (bug fixes)

📋 Changelog Preview

This is how your changes will appear in the changelog.
Entries from this PR are highlighted with a left border (blockquote style).

---

Bug Fixes 🐛

• (errors) Separate informational notes from actionable alternatives in ContextError by BYK in #651

• Fix set-commits --auto, document release workflow pitfalls by BYK in #650

Internal Changes 🔧

• Regenerate skill files and command docs by github-actions[bot] in eb1b19e7

---

_{🤖 This preview updates automatically when you update the PR.}

[github-actions]

Codecov Results 📊

✅ 134 passed | Total: 134 | Pass Rate: 100% | Execution Time: 0ms

📊 Comparison with Base Branch

Metric	Change
Total Tests	—
Passed Tests	—
Failed Tests	—
Skipped Tests	—

✨ No test changes detected

All tests are passing successfully.

✅ Patch coverage is 95.65%. Project has 1373 uncovered lines.
✅ Project coverage is 95.65%. Comparing base (base) to head (head).

Files with missing lines (1)

File	Patch %	Lines
src/lib/api/releases.ts	95.45%	⚠️ 1 Missing

Coverage diff

@@            Coverage Diff             @@
##          main       #PR       +/-##
==========================================
+ Coverage    95.64%    95.65%    +0.01%
==========================================
  Files          219       219         —
  Lines        31550     31569       +19
  Branches         0         0         —
==========================================
+ Hits         30176     30196       +20
- Misses        1374      1373        -1
- Partials         0         0         —

---

Generated by Codecov Action

[github-actions]

PR Preview Action v1.8.1
🚀 View preview at https://cli.sentry.dev/pr-preview/pr-650/
Built to branch gh-pages at 2026-04-03 17:37 UTC. Preview will be ready when the GitHub Pages deployment is complete.

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}