chore: improve release notes pipeline #481
Conversation
- Switch to @changesets/changelog-github for PR/author links in CHANGELOG.md - Add comprehensive changeset README with template and contributor guidance - Remove release:local script (CI-only releases)
📝 WalkthroughWalkthroughExpanded Changesets documentation, switched Changesets changelog config to GitHub adapter with repository context, removed a local release script and added the GitHub changelog package, and introduced a GitHub Actions workflow that polishes release notes using Claude and updates GitHub Releases. Changes
Sequence Diagram(s)sequenceDiagram
participant GH as GitHub (release event)
participant Runner as Actions Runner
participant Repo as Repository (checkout)
participant GHCLI as gh CLI
participant Claude as Claude Code Action
participant GitHubAPI as GitHub Releases API
GH->>Runner: release published (tag)
Runner->>Repo: actions/checkout
Runner->>GHCLI: gh release view --json body --repo ...
GHCLI-->>Runner: release body
Runner->>Claude: send prompt + release body (CLAUDE_CODE_OAUTH_TOKEN)
Claude-->>Runner: release-title.txt + polished-notes.md
alt both files exist
Runner->>GitHubAPI: update release title and body (GITHUB_TOKEN)
else only polished-notes.md
Runner->>GitHubAPI: update release body (preserve title)
else neither
Runner-->>GH: no change
end
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Poem
🚥 Pre-merge checks | ✅ 2 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (2 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Review CompleteYour review story is ready! Comment !reviewfast on this PR to re-generate the story. |
Transforms raw changelog into user-friendly release notes when a GitHub Release is published. Uses Claude Code Action to: - Generate concise release title (e.g., "v0.18.0 - OPSX Workflow") - Rewrite changelog as developer-friendly release notes - Remove noise (commit hashes, PR numbers, internal changes) Requires CLAUDE_CODE_OAUTH_TOKEN secret (from claude setup-token).
TabishB
changed the title
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (1)
.changeset/README.md (1)
53-74: Consider a brief note on “tooling changes” when they affect release outputs.
Since this repo’s tooling can change published artifacts (e.g., changelog formatting), you may want to clarify whether release-process/tooling changes should get a changeset when they affect end users.
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
⛔ Files ignored due to path filters (1)
pnpm-lock.yamlis excluded by!**/pnpm-lock.yaml
📒 Files selected for processing (3)
.changeset/README.md.changeset/config.jsonpackage.json
🧰 Additional context used
🧠 Learnings (2)
📚 Learning: 2025-11-25T01:08:19.004Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Applies to openspec/changes/*/proposal.md : Ensure `proposal.md` includes sections: Why (1-2 sentences), What Changes (bullet list with breaking change markers), and Impact (affected specs and code)
Applied to files:
.changeset/README.md
📚 Learning: 2025-11-25T01:08:02.839Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:02.839Z
Learning: Use `@/openspec/AGENTS.md` to learn how to create and apply change proposals, spec format and conventions, and project structure and guidelines
Applied to files:
.changeset/README.md
🔇 Additional comments (5)
.changeset/README.md (3)
21-52: Changeset template looks good and user-oriented.
The structure (frontmatter + user-facing sections) is pragmatic and should produce higher-quality changelog entries.
75-95: “Do/Don’t” examples are effective.
Nice guidance that will prevent low-signal entries like “Fixed #123” (Lines 92-95).
1-20: ✓ Workflow automation is correctly configured and matches the documentation.Verification confirms that
release-prepare.ymlimplements the described flow: it runs on pushes tomainand useschangesets/action@v1to open/update the Version Packages PR and publish when merged (viapnpm run release:ci). ThecreateGithubReleases: truesetting creates GitHub releases automatically. The documented workflow is accurate and no changes are needed.package.json (1)
63-63: Ensure CI has GITHUB_TOKEN permissions for changelog generation.
The@changesets/changelog-githubv0.5.2 package exists and is compatible with your current @changesets/cli and Node versions. For changelog generation to succeed, your CI environment must have GITHUB_TOKEN with the necessary permissions for PR/commit lookups duringchangeset version..changeset/config.json (1)
3-6: Ensure CIGITHUB_TOKENhas the required scopes for changelog generation.
Therepo: "Fission-AI/OpenSpec"format is correct. However, verify that your CI workflow grants theGITHUB_TOKENat minimum these permissions:contents: write(to update files and create refs) andpull-requests: write(to create the release PR). Without these scopes, changelog generation will fail.
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Fix all issues with AI agents
In @.github/workflows/polish-release-notes.yml:
- Line 32: Add the repository secret named CLAUDE_CODE_OAUTH_TOKEN (exactly that
name) in GitHub > Settings > Secrets and variables > Actions so the workflow can
access it; create a new repository secret, paste the Anthropic/Claude Code OAuth
token as the value, save it, and ensure any CI users who need to update it have
the token source and rotation policy (do not hardcode the token into the repo).
🧹 Nitpick comments (1)
.github/workflows/polish-release-notes.yml (1)
122-137: LGTM: Robust fallback logic handles partial failures gracefully.The conditional file checks ensure the release is only updated when Claude successfully generates output, with appropriate fallbacks for each scenario.
💡 Optional: Add debugging output for troubleshooting
Consider logging the generated files for easier debugging if the action doesn't behave as expected:
- name: Update release env: GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} run: | TAG="${{ github.event.release.tag_name }}" + + echo "Generated files:" + ls -la *.md *.txt 2>/dev/null || echo "No output files found" if [ -f "polished-notes.md" ] && [ -f "release-title.txt" ]; then + echo "Title: $(cat release-title.txt)" TITLE=$(cat release-title.txt) gh release edit "$TAG" --title "$TITLE" --notes-file polished-notes.md echo "Updated: $TITLE"
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
.github/workflows/polish-release-notes.yml
🧰 Additional context used
🪛 actionlint (1.7.10)
.github/workflows/polish-release-notes.yml
34-34: input "direct_prompt" is not defined in action "anthropics/claude-code-action@v1". available inputs are "additional_permissions", "allowed_bots", "allowed_non_write_users", "anthropic_api_key", "assignee_trigger", "base_branch", "bot_id", "bot_name", "branch_prefix", "claude_args", "claude_code_oauth_token", "github_token", "label_trigger", "path_to_bun_executable", "path_to_claude_code_executable", "plugin_marketplaces", "plugins", "prompt", "settings", "show_full_output", "track_progress", "trigger_phrase", "use_bedrock", "use_commit_signing", "use_foundry", "use_sticky_comment", "use_vertex"
(action)
🔇 Additional comments (5)
.github/workflows/polish-release-notes.yml (5)
1-10: LGTM: Workflow trigger and permissions are correctly configured.The
release: publishedtrigger andcontents: writepermission are appropriate for modifying release notes.
11-18: LGTM: Repository check prevents unintended fork execution.The repository guard and checkout setup follow best practices.
20-27: LGTM: Release body retrieval is correctly implemented.The use of
gh release viewwith proper token authentication and tag reference is appropriate.
1-137: Excellent automation approach for release note polishing.This workflow effectively automates the transformation of raw changelogs into polished, developer-friendly release notes. The comprehensive prompt with clear voice guidelines, formatting rules, and examples ensures consistent output quality. Once the critical
direct_promptissue is fixed, this will be a valuable addition to the release workflow.
28-121: Critical: Two input parameters are incompatible withanthropics/claude-code-action@v1.The action v1 removed the
direct_promptandclaude_code_oauth_tokeninputs in favor ofpromptandanthropic_api_key. The workflow will fail without these corrections.🔧 Fix both input parameter names
- name: Transform release notes with Claude uses: anthropics/claude-code-action@v1 id: claude with: - claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }} + anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} github_token: ${{ secrets.GITHUB_TOKEN }} - direct_prompt: | + prompt: | Transform the changelog in `current-notes.md` into release notes for OpenSpec ${{ github.event.release.tag_name }}.Update the secrets configuration accordingly: rename
CLAUDE_CODE_OAUTH_TOKENtoANTHROPIC_API_KEYin your repository settings.Likely an incorrect or invalid review comment.
| uses: anthropics/claude-code-action@v1 | ||
| id: claude | ||
| with: | ||
| claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }} |
There was a problem hiding this comment.
🛠️ Refactor suggestion | 🟠 Major
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# First, let's look at the workflow file to understand the context
echo "=== Examining the workflow file ==="
cat .github/workflows/polish-release-notes.ymlRepository: Fission-AI/OpenSpec
Length of output: 4518
🏁 Script executed:
#!/bin/bash
# Search for documentation about CLAUDE_CODE_OAUTH_TOKEN
echo "=== Searching for CLAUDE_CODE_OAUTH_TOKEN documentation ==="
rg -i "CLAUDE_CODE_OAUTH_TOKEN" -C 3
echo -e "\n=== Searching for setup instructions ==="
find . -type f \( -name "README*" -o -name "CONTRIBUTING*" -o -name "SETUP*" -o -name "*.md" \) | head -20 | xargs rg -i "secret" --type md -C 2 2>/dev/null || echo "No matches found"Repository: Fission-AI/OpenSpec
Length of output: 352
🏁 Script executed:
#!/bin/bash
# Check if there's any CI configuration or environment setup documentation
echo "=== Looking for CI/setup documentation ==="
git ls-files | grep -E "(\.github|setup|config|README|CONTRIBUTING)" | head -30Repository: Fission-AI/OpenSpec
Length of output: 1570
Ensure the CLAUDE_CODE_OAUTH_TOKEN secret is configured in repository settings.
This workflow requires a repository secret named CLAUDE_CODE_OAUTH_TOKEN to authenticate with Claude via the Anthropic Claude Code Action. This token must be set up in the repository's secrets before the workflow can execute on release publication.
🤖 Prompt for AI Agents
In @.github/workflows/polish-release-notes.yml at line 32, Add the repository
secret named CLAUDE_CODE_OAUTH_TOKEN (exactly that name) in GitHub > Settings >
Secrets and variables > Actions so the workflow can access it; create a new
repository secret, paste the Anthropic/Claude Code OAuth token as the value,
save it, and ensure any CI users who need to update it have the token source and
rotation policy (do not hardcode the token into the repo).
Summary
End-to-end improvements to how release notes are generated and presented:
@changesets/changelog-github— CHANGELOG.md entries now include PR links, commit hashes, and author attributionPipeline Flow
Changes
Changelog Generation
@changesets/changelog-githubfor automatic PR/author linksrelease:localscript (CI-only releases)Changeset Guidance
Release Notes Polish (new workflow)
release: publishedv0.18.0 - OPSX Experimental WorkflowCLAUDE_CODE_OAUTH_TOKENsecretSetup Required
For the polish workflow to work:
Then add
CLAUDE_CODE_OAUTH_TOKENto GitHub repository secrets.Test plan
pnpm changesetstill works locally🤖 Generated with Claude Code
Summary by CodeRabbit
Documentation
Chores
✏️ Tip: You can customize this high-level summary in your review settings.