feat(changelog): Add changelog preview action and CLI command #669

BYK · 2025-12-26T13:37:51Z

Summary

Adds a new craft changelog CLI command and a reusable GitHub Actions workflow that previews how PRs will appear in the changelog.

New CLI Command

# Generate changelog from latest tag
craft changelog

# Generate changelog with PR preview (highlighted)
craft changelog --pr 123

# Output as JSON (includes bumpType for automation)
craft changelog --pr 123 --format json

JSON Output

{
  "changelog": "### New Features ✨\n\n> - feat: Add feature by @user in #123",
  "bumpType": "minor",
  "totalCommits": 15,
  "matchedCommitsWithSemver": 12
}

Reusable Workflow

Other repos can use the changelog preview by adding:

name: Changelog Preview
on:
  pull_request:
    types: [opened, synchronize, reopened, edited, labeled]

jobs:
  changelog-preview:
    uses: getsentry/craft/.github/workflows/changelog-preview.yml@v2
    secrets: inherit

Features

Shows suggested version bump (major/minor/patch) based on commit categories
Highlights PR entries with blockquote style
Auto-updates when PR is modified (title, description, labels, commits)

Example Comment

Architecture

Refactored changelog generation into clean separation of concerns:

fetchRawCommitInfo - Fetches commit/PR data from git and GitHub
categorizeCommits - Groups commits into categories with bump type detection
serializeChangelog - Renders to markdown

The generateChangelogWithHighlight function uses a "sandwich" approach:

Fetch raw commits up to base branch
Add current PR with highlight: true
Run categorization on combined list
Serialize to markdown

Files Changed

src/commands/changelog.ts - New CLI command
src/utils/changelog.ts - Refactored with new architecture
.github/workflows/changelog-preview.yml - Reusable workflow
install/action.yml - Shared Craft installation action
docs/src/content/docs/github-actions.md - Documentation
README.md - Updated with GitHub Actions section

Add a new GitHub Action that posts changelog previews on PRs, showing contributors how their changes will appear in the changelog. Changes: - New `craft changelog` CLI command with `--pr` option for highlighting - New `changelog-preview/action.yml` that posts/updates PR comments - Shared `install/action.yml` for Craft installation (used by both actions) - Refactored main action.yml to use shared install action - Documentation in README and docs site

github-actions · 2025-12-26T13:38:32Z

PR Preview Action v1.7.0
🚀 View preview at https://getsentry.github.io/craft/pr-preview/pr-669/
Built to branch `gh-pages` at 2025-12-26 17:32 UTC. Preview will be ready when the GitHub Pages deployment is complete.

Use local ./install action and inline the preview steps since the composite action references getsentry/craft/install@master which doesn't exist on master yet.

github-actions · 2025-12-26T14:08:07Z

Suggested Version Bump

🟡 Minor (new features)

📋 Changelog Preview

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

New Features ✨

feat(changelog): Add changelog preview action and CLI command by @BYK in #669

Documentation 📚

docs: New documentation site! by @BYK in #668

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

The previous approach relied on GitHub's associatedPullRequests API which only works for merged commits. Now we identify PR commits by comparing HEAD with the base branch and highlight those specific commits. Changes: - Replace --pr option with --base option for specifying the PR base branch - Highlight commits that are in HEAD but not in base (i.e., PR commits) - Update workflow and action to fetch base and use new option

- Add --until option to limit changelog range - Fetch current PR info from GitHub API - Add PR to appropriate category with highlighting - Uses blockquote style for highlighted entries

Craft now fetches PR info from GitHub API which includes the base branch, then computes the merge base internally. This simplifies the workflow.

Other repositories can now call this workflow directly: ```yaml jobs: changelog-preview: uses: getsentry/craft/.github/workflows/changelog-preview.yml@v2 secrets: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} ``` - Added workflow_call trigger with optional craft-version input - Install Craft from release for external repos - Build from source only for getsentry/craft (dogfooding)

Callers should use 'secrets: inherit' to pass secrets

.github/workflows/changelog-preview.yml

docs/src/content/docs/github-actions.md

- Use install/action.yml instead of inline installation in workflow - Add build-from-source support to install action for craft repo - Remove duplicate changelog-preview/action.yml (use reusable workflow) - Add 'edited' and 'labeled' PR trigger types for title/label changes - Change 'push changes' to 'update the PR' in comment text - Use heredoc instead of temp file for gh api call - Reference getsentry/publish repo in docs as example - Document label exclusion option for skipping changelog entries

Can't reference install action from master as it's not merged yet. For external repos, install from release. For craft repo, build from source.

.github/workflows/changelog-preview.yml

action.yml

src/utils/changelog.ts

src/commands/changelog.ts

- Use install action with PR ref in changelog-preview workflow - Use relative path ./install in main action.yml - Change CurrentPRInfo.number from string to number type - Make fetchPRInfo errors fatal (remove try/catch) - Make merge base computation errors fatal - Update all prInfo.number usages to convert to string where needed

- Add RawChangelogData interface for intermediate representation - Create generateRawChangelog function for data gathering - Create injectCurrentPR function to add PR to raw data - Create serializeChangelog function for markdown formatting - Update generateChangelogWithHighlight to use sandwich approach: 1. Generate raw changelog up to merge base 2. Inject current PR into the data 3. Serialize with PR highlighting - Remove highlight property from PullRequest interface - Make currentPRNumber required in generateChangelogWithHighlight - Use generateChangesetFromGit when --pr not specified

Using the PR's base branch tip directly (origin/{base.ref}) gives a more accurate changelog preview, since it includes all commits currently on the base branch that will be part of the final changelog when the PR is merged.

Split RawChangelogData into: - RawChangelogData: just the changelog entries (categories, leftovers, config) - ChangelogStats: metrics for auto-versioning (bumpType, totalCommits, etc.) generateRawChangelog now returns RawChangelogResult containing both.

The function was only used in one place, so inline the logic directly.

- Split data gathering from categorization: - fetchRawCommitInfo: fetches commit/PR data from git and GitHub - categorizeCommits: groups commits into categories - serializeChangelog: renders to markdown - generateChangelogWithHighlight now: 1. Fetches raw commit info 2. Adds current PR with highlight flag to the list 3. Runs categorization on combined list (no duplicate logic) 4. Serializes to markdown - Add highlight flag to PullRequest and Commit interfaces - Serialization uses entry.highlight instead of comparing PR numbers - Add --format json option to changelog command: Returns { changelog, bumpType, totalCommits, matchedCommitsWithSemver }

- Use --format json to get bumpType from craft changelog - Display bump type with colored badge (🔴 Major, 🟡 Minor, 🟢 Patch) - Update docs to reflect new comment format

…mment - Version bump is now ## header appearing first - Use temp file instead of heredoc (safer with arbitrary content) - Use unique heredoc marker CRAFT_CHANGELOG_COMMENT_END - Use -F body=@file for gh api calls

Follow up to #669. #skip-changelog

Fixes the changelog preview workflow and `--pr` flag to properly respect the `#skip-changelog` magic word. ### Changes - Fix `inputs` context error in workflow (not available for `pull_request` trigger) - Add `prSkipped` field to JSON output when PR is excluded - Show "This PR will not appear in the changelog" message when PR is skipped - Consolidate skip logic into `shouldExcludePR` with new `body` parameter - Early-exit in `generateChangelogWithHighlight` to skip unnecessary work Follow-up to #669.

BYK added 2 commits December 26, 2025 17:06

ci: Add changelog preview workflow for testing

be12666

ci: Fix changelog preview workflow for testing

749a43b

Use local ./install action and inline the preview steps since the composite action references getsentry/craft/install@master which doesn't exist on master yet.

BYK added 10 commits December 26, 2025 17:13

debug: Add verbose output to changelog preview workflow

de8d3ee

ci: Build craft from source for testing (changelog cmd not released)

3f80c2b

fix: Generate changelog up to merge base and inject current PR

4391678

- Add --until option to limit changelog range - Fetch current PR info from GitHub API - Add PR to appropriate category with highlighting - Uses blockquote style for highlighted entries

fix: Add GITHUB_TOKEN env for Craft API access

f2aefe9

fix: Suppress stderr to hide node deprecation warning

9647967

refactor: Remove --until flag, compute merge base from PR's base branch

06a9014

Craft now fetches PR info from GitHub API which includes the base branch, then computes the merge base internally. This simplifies the workflow.

fix: Add setup-node step for dogfooding

e1756f3

fix: Remove explicit secrets requirement from workflow_call

8f7e9d2

Callers should use 'secrets: inherit' to pass secrets

BYK commented Dec 26, 2025

View reviewed changes

BYK added 2 commits December 26, 2025 18:31

fix: Inline install logic in reusable workflow

e5ecfc3

Can't reference install action from master as it's not merged yet. For external repos, install from release. For craft repo, build from source.

BYK commented Dec 26, 2025

View reviewed changes

BYK added 8 commits December 26, 2025 19:21

refactor: Use base branch tip instead of merge-base

491804b

Using the PR's base branch tip directly (origin/{base.ref}) gives a more accurate changelog preview, since it includes all commits currently on the base branch that will be part of the final changelog when the PR is merged.

refactor: Inline injectCurrentPR into generateChangelogWithHighlight

2c0f6d8

The function was only used in one place, so inline the logic directly.

feat: Display suggested version bump in changelog preview comment

abbe627

- Use --format json to get bumpType from craft changelog - Display bump type with colored badge (🔴 Major, 🟡 Minor, 🟢 Patch) - Update docs to reflect new comment format

style: Make version bump more prominent with its own header

5777299

BYK marked this pull request as ready for review December 26, 2025 17:30

betegon self-requested a review December 26, 2025 17:33

betegon approved these changes Dec 26, 2025

View reviewed changes

BYK changed the title ~~feat: Add changelog preview GitHub Action~~ feat(changelog): Add changelog preview action and CLI command Dec 26, 2025

BYK merged commit 29cfe75 into master Dec 26, 2025
16 checks passed

BYK deleted the feat/changelog-preview-action branch December 26, 2025 18:18

BYK added a commit that referenced this pull request Dec 26, 2025

ref: Use the proper install action version in workflow

5954de1

Follow up to #669. #skip-changelog

BYK mentioned this pull request Dec 26, 2025

fix(changelog): Handle #skip-changelog in preview workflow #670

Merged

sentry-release-bot bot mentioned this pull request Dec 29, 2025

publish: getsentry/[email protected] getsentry/publish#6852

Closed

7 tasks

Uh oh!

feat(changelog): Add changelog preview action and CLI command #669

feat(changelog): Add changelog preview action and CLI command #669

Uh oh!

Conversation

BYK commented Dec 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

New CLI Command

JSON Output

Reusable Workflow

Features

Example Comment

Architecture

Files Changed

Uh oh!

github-actions bot commented Dec 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Built to branch gh-pages at 2025-12-26 17:32 UTC. Preview will be ready when the GitHub Pages deployment is complete.

Uh oh!

github-actions bot commented Dec 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Suggested Version Bump

📋 Changelog Preview

New Features ✨

Documentation 📚

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

BYK commented Dec 26, 2025 •

edited

Loading

github-actions bot commented Dec 26, 2025 •

edited

Loading

Built to branch `gh-pages` at 2025-12-26 17:32 UTC.
Preview will be ready when the GitHub Pages deployment is complete.

github-actions bot commented Dec 26, 2025 •

edited

Loading