From 598b4a1ed5f705dad2140d8697defc9b9c7b2533 Mon Sep 17 00:00:00 2001
From: Burak Yigit Kaya <byk@sentry.io>
Date: Thu, 15 Jan 2026 17:33:31 +0000
Subject: [PATCH 1/8] feat(github): Add comment option to changelog-preview
 workflow

Add a `comment` input to the changelog-preview workflow that allows
users to choose between posting PR comments (default) or creating check
runs with job summaries.

When `comment: false`:
- Creates a neutral check run named "Changelog" with the semver impact
- Includes full changelog preview in the check run summary
- Writes to GitHub Actions job summary for easy access
- Reduces notification noise compared to PR comments

When `comment: true` (default):
- Preserves existing behavior of posting/updating PR comments
- Maintains backward compatibility for all existing users

For Craft's own repository, the workflow automatically uses check run
mode when triggered via pull_request events (dogfooding).

Documentation updated to explain both modes with examples, pros/cons,
and required permissions for each mode.
---
 .github/workflows/changelog-preview.yml | 129 +++++++++++++++++++-----
 docs/src/content/docs/github-actions.md |  93 +++++++++++++++--
 2 files changed, 192 insertions(+), 30 deletions(-)

diff --git a/.github/workflows/changelog-preview.yml b/.github/workflows/changelog-preview.yml
index ae66852a..7832befc 100644
--- a/.github/workflows/changelog-preview.yml
+++ b/.github/workflows/changelog-preview.yml
@@ -8,12 +8,13 @@ on:
   #
   # 1. Grant required permissions:
   #    - contents: read        (to checkout repo and read git history)
-  #    - pull-requests: write  (to post/update PR comments)
+  #    - pull-requests: write  (to post/update PR comments in comment mode)
+  #    - checks: write         (to create check runs in check run mode)
   #
   # 2. Inherit secrets:
   #    - secrets: inherit      (ensures caller's GITHUB_TOKEN is used)
   #
-  # Example caller workflow:
+  # Example caller workflow (comment mode):
   #
   #   on:
   #     pull_request:
@@ -28,6 +29,19 @@ on:
   #       uses: getsentry/craft/.github/workflows/changelog-preview.yml@v2
   #       secrets: inherit
   #
+  # Example caller workflow (check run mode):
+  #
+  #   permissions:
+  #     contents: read
+  #     checks: write
+  #
+  #   jobs:
+  #     changelog-preview:
+  #       uses: getsentry/craft/.github/workflows/changelog-preview.yml@v2
+  #       with:
+  #         comment: false
+  #       secrets: inherit
+  #
   workflow_call:
     inputs:
       working-directory:
@@ -39,6 +53,11 @@ on:
         description: 'Version of Craft to use (tag or "latest")'
         required: false
         type: string
+      comment:
+        description: 'Post changelog as PR comment (true) or as check run with job summary (false)'
+        required: false
+        type: boolean
+        default: true
 
   # Also run on PRs in this repository (for dogfooding)
   # Includes 'edited' and 'labeled' to update when PR title/description/labels change
@@ -47,7 +66,8 @@ on:
 
 permissions:
   contents: read
-  pull-requests: write
+  pull-requests: write # For comment mode
+  checks: write # For check run mode
 
 jobs:
   preview:
@@ -137,9 +157,70 @@ jobs:
             *) BUMP_BADGE="⚪ **None** (no version bump detected)" ;;
           esac
 
-          # Build comment body using a temp file (safer than heredoc)
-          COMMENT_FILE=$(mktemp)
-          cat > "$COMMENT_FILE" << CRAFT_CHANGELOG_COMMENT_END
+          # Create short description with emoji for check run title
+          case "$BUMP_TYPE" in
+            major) BUMP_SHORT="🔴 Major" ;;
+            minor) BUMP_SHORT="🟡 Minor" ;;
+            patch) BUMP_SHORT="🟢 Patch" ;;
+            *) BUMP_SHORT="⚪ None" ;;
+          esac
+
+          # Determine mode: use check run mode when comment is false OR when running internally (no input)
+          USE_COMMENT_MODE="${{ inputs.comment }}"
+          if [[ "$USE_COMMENT_MODE" == "false" ]] || [[ -z "$USE_COMMENT_MODE" ]]; then
+            # Check run mode (new feature or internal dogfooding)
+            echo "Using check run mode..."
+            
+            # 1. Create check run via GitHub API
+            echo "Creating check run..."
+            gh api -X POST \
+              "repos/$GITHUB_REPOSITORY/check-runs" \
+              -f name="Changelog" \
+              -f head_sha="${{ github.event.pull_request.head.sha || github.sha }}" \
+              -f status="completed" \
+              -f conclusion="neutral" \
+              -f output[title]="$BUMP_SHORT" \
+              -f output[summary]="$CHANGELOG"
+            
+            echo "✓ Check run created"
+            
+            # 2. Write to job summary
+            PR_URL="${GITHUB_SERVER_URL}/${GITHUB_REPOSITORY}/pull/${PR_NUMBER}"
+            
+            cat >> $GITHUB_STEP_SUMMARY << CRAFT_CHANGELOG_SUMMARY_END
+          # Changelog Preview for PR #${PR_NUMBER}
+
+          [→ View PR #${PR_NUMBER}](${PR_URL})
+
+          ## Semver Impact of This PR
+
+          ${BUMP_BADGE}
+
+          <details>
+          <summary>📋 Changelog Preview</summary>
+
+          This is how your changes will appear in the changelog.
+          Entries from this PR are highlighted with a left border (blockquote style).
+
+          ---
+
+          ${CHANGELOG}
+
+          ---
+
+          </details>
+
+          <sub>💡 This preview is available in the Actions run summary. [View all workflow runs](${GITHUB_SERVER_URL}/${GITHUB_REPOSITORY}/actions/workflows/changelog-preview.yml).</sub>
+          CRAFT_CHANGELOG_SUMMARY_END
+            
+            echo "✓ Job summary written"
+          else
+            # Comment mode (original behavior)
+            echo "Using comment mode..."
+            
+            # Build comment body using a temp file (safer than heredoc)
+            COMMENT_FILE=$(mktemp)
+            cat > "$COMMENT_FILE" << CRAFT_CHANGELOG_COMMENT_END
           <!-- craft-changelog-preview -->
           ## Semver Impact of This PR
 
@@ -162,22 +243,24 @@ jobs:
           <sub>🤖 This preview updates automatically when you update the PR.</sub>
           CRAFT_CHANGELOG_COMMENT_END
 
-          # Find existing comment with our marker
-          COMMENT_ID=$(gh api \
-            "repos/$GITHUB_REPOSITORY/issues/$PR_NUMBER/comments" \
-            --jq '.[] | select(.body | contains("<!-- craft-changelog-preview -->")) | .id' \
-            | head -1)
-
-          if [[ -n "$COMMENT_ID" ]]; then
-            echo "Updating existing comment $COMMENT_ID..."
-            gh api -X PATCH \
-              "repos/$GITHUB_REPOSITORY/issues/comments/$COMMENT_ID" \
-              -F body=@"$COMMENT_FILE"
-          else
-            echo "Creating new comment..."
-            gh api -X POST \
+            # Find existing comment with our marker
+            COMMENT_ID=$(gh api \
               "repos/$GITHUB_REPOSITORY/issues/$PR_NUMBER/comments" \
-              -F body=@"$COMMENT_FILE"
-          fi
+              --jq '.[] | select(.body | contains("<!-- craft-changelog-preview -->")) | .id' \
+              | head -1)
 
-          rm -f "$COMMENT_FILE"
+            if [[ -n "$COMMENT_ID" ]]; then
+              echo "Updating existing comment $COMMENT_ID..."
+              gh api -X PATCH \
+                "repos/$GITHUB_REPOSITORY/issues/comments/$COMMENT_ID" \
+                -F body=@"$COMMENT_FILE"
+            else
+              echo "Creating new comment..."
+              gh api -X POST \
+                "repos/$GITHUB_REPOSITORY/issues/$PR_NUMBER/comments" \
+                -F body=@"$COMMENT_FILE"
+            fi
+
+            rm -f "$COMMENT_FILE"
+            echo "✓ Comment posted"
+          fi
diff --git a/docs/src/content/docs/github-actions.md b/docs/src/content/docs/github-actions.md
index 6abee55d..dd2f0ad5 100644
--- a/docs/src/content/docs/github-actions.md
+++ b/docs/src/content/docs/github-actions.md
@@ -142,9 +142,85 @@ jobs:
 
 ### Inputs
 
-| Input           | Description                               | Default  |
-| --------------- | ----------------------------------------- | -------- |
-| `craft-version` | Version of Craft to use (tag or "latest") | `latest` |
+| Input               | Description                                                                  | Default  |
+| ------------------- | ---------------------------------------------------------------------------- | -------- |
+| `working-directory` | Directory to run Craft in (relative to repo root)                            | `.`      |
+| `craft-version`     | Version of Craft to use (tag or "latest")                                    | `latest` |
+| `comment`           | Post changelog as PR comment (true) or as check run with job summary (false) | `true`   |
+
+### Output Modes
+
+The workflow supports two output modes for displaying changelog previews:
+
+#### Comment Mode (Default)
+
+Posts the changelog preview as a PR comment that updates automatically:
+
+```yaml
+jobs:
+  changelog-preview:
+    uses: getsentry/craft/.github/workflows/changelog-preview.yml@v2
+    with:
+      comment: true # or omit for default
+    secrets: inherit
+```
+
+**Pros:**
+
+- Changelog visible directly on PR page
+- All team members see updates immediately
+- Familiar commenting interface
+
+**Cons:**
+
+- Creates notification noise on every update
+- Multiple updates trigger multiple notifications
+- Can clutter PR conversation on active branches
+
+**Required permissions:**
+
+```yaml
+permissions:
+  contents: read
+  pull-requests: write
+```
+
+#### Check Run Mode
+
+Creates a neutral check run with detailed output and writes to the Actions job summary:
+
+```yaml
+jobs:
+  changelog-preview:
+    uses: getsentry/craft/.github/workflows/changelog-preview.yml@v2
+    with:
+      comment: false
+    secrets: inherit
+```
+
+**Pros:**
+
+- Minimal notification noise
+- Cleaner PR interface
+- Semver impact visible in checks section
+- Full changelog available in check details and Actions summary
+
+**Cons:**
+
+- Requires clicking through to see full changelog
+- Less immediate visibility than comment
+
+**Required permissions:**
+
+```yaml
+permissions:
+  contents: read
+  checks: write
+```
+
+:::tip
+Craft itself uses check run mode to avoid notification noise. You can see it in action on any PR in the [getsentry/craft repository](https://github.com/getsentry/craft/pulls).
+:::
 
 ### Pinning a Specific Version
 
@@ -168,8 +244,8 @@ jobs:
 3. **Categorizes the PR** - Matches the PR to changelog categories based on labels and commit patterns
 4. **Suggests version bump** - Based on matched categories with semver fields (major/minor/patch)
 5. **Highlights PR entries** - The current PR is rendered with blockquote style (displayed with a left border in GitHub)
-6. **Posts a comment** - Creates or updates a comment on the PR with the changelog preview
-7. **Auto-updates** - The comment is automatically updated when you update the PR (push commits, edit title/description, or change labels)
+6. **Displays the preview** - Posts as a PR comment (default) or creates a neutral check run with job summary (when `comment: false`)
+7. **Auto-updates** - The preview is automatically updated when you update the PR (push commits, edit title/description, or change labels)
 
 :::note
 The version bump suggestion requires categories in your `.github/release.yml` to have
@@ -225,7 +301,8 @@ The workflow requires specific permissions and secrets to function correctly:
 **Permissions** (required):
 
 - `contents: read` - Allows the workflow to checkout your repository and read git history for changelog generation
-- `pull-requests: write` - Allows the workflow to post and update comments on pull requests
+- `pull-requests: write` - Required for comment mode (default) to post and update comments on pull requests
+- `checks: write` - Required for check run mode (when `comment: false`) to create check runs
 
 **Secrets**:
 
@@ -236,7 +313,9 @@ The workflow requires specific permissions and secrets to function correctly:
 - The repository should have a git history with tags for the changelog to be meaningful
 
 :::note[Why are these permissions needed?]
-GitHub Actions reusable workflows use permission intersection - the final permissions are the intersection of what the caller grants and what the workflow declares. By explicitly declaring these permissions in your workflow file, you ensure the workflow can access your repository and post comments, even for private repositories.
+GitHub Actions reusable workflows use permission intersection - the final permissions are the intersection of what the caller grants and what the workflow declares. By explicitly declaring these permissions in your workflow file, you ensure the workflow can access your repository and perform the necessary actions, even for private repositories.
+
+Note: You only need `pull-requests: write` for comment mode OR `checks: write` for check run mode, not both. However, it's safe to grant both permissions if you're unsure which mode you'll use.
 :::
 
 ## Skipping Changelog Entries

From 4eb13d8030199b9b2a75b89af7138eaab988a792 Mon Sep 17 00:00:00 2001
From: Burak Yigit Kaya <byk@sentry.io>
Date: Thu, 15 Jan 2026 17:39:25 +0000
Subject: [PATCH 2/8] fix: Improve check run title and remove footer link

- Add 'Semver impact: ' prefix to check run title for clarity
- Remove unnecessary footer link from job summary
---
 .github/workflows/changelog-preview.yml | 10 ++++------
 1 file changed, 4 insertions(+), 6 deletions(-)

diff --git a/.github/workflows/changelog-preview.yml b/.github/workflows/changelog-preview.yml
index 7832befc..5b547dcd 100644
--- a/.github/workflows/changelog-preview.yml
+++ b/.github/workflows/changelog-preview.yml
@@ -159,10 +159,10 @@ jobs:
 
           # Create short description with emoji for check run title
           case "$BUMP_TYPE" in
-            major) BUMP_SHORT="🔴 Major" ;;
-            minor) BUMP_SHORT="🟡 Minor" ;;
-            patch) BUMP_SHORT="🟢 Patch" ;;
-            *) BUMP_SHORT="⚪ None" ;;
+            major) BUMP_SHORT="Semver impact: 🔴 Major" ;;
+            minor) BUMP_SHORT="Semver impact: 🟡 Minor" ;;
+            patch) BUMP_SHORT="Semver impact: 🟢 Patch" ;;
+            *) BUMP_SHORT="Semver impact: ⚪ None" ;;
           esac
 
           # Determine mode: use check run mode when comment is false OR when running internally (no input)
@@ -209,8 +209,6 @@ jobs:
           ---
 
           </details>
-
-          <sub>💡 This preview is available in the Actions run summary. [View all workflow runs](${GITHUB_SERVER_URL}/${GITHUB_REPOSITORY}/actions/workflows/changelog-preview.yml).</sub>
           CRAFT_CHANGELOG_SUMMARY_END
             
             echo "✓ Job summary written"

From 2d5a2ac90bd13291854ae7faf3efb35dae75ff6a Mon Sep 17 00:00:00 2001
From: Burak Yigit Kaya <byk@sentry.io>
Date: Thu, 15 Jan 2026 17:49:38 +0000
Subject: [PATCH 3/8] fix: Use proper JSON input for check run creation

- Use jq to safely construct JSON payload
- Add details_url to link to Actions run
- Include full changelog in output.summary
- Add explicit API version header
---
 .github/workflows/changelog-preview.yml | 58 ++++++++++++++++++++-----
 1 file changed, 48 insertions(+), 10 deletions(-)

diff --git a/.github/workflows/changelog-preview.yml b/.github/workflows/changelog-preview.yml
index 5b547dcd..6cf1d029 100644
--- a/.github/workflows/changelog-preview.yml
+++ b/.github/workflows/changelog-preview.yml
@@ -171,22 +171,60 @@ jobs:
             # Check run mode (new feature or internal dogfooding)
             echo "Using check run mode..."
             
-            # 1. Create check run via GitHub API
+            HEAD_SHA="${{ github.event.pull_request.head.sha || github.sha }}"
+            DETAILS_URL="${GITHUB_SERVER_URL}/${GITHUB_REPOSITORY}/actions/runs/${GITHUB_RUN_ID}"
+            PR_URL="${GITHUB_SERVER_URL}/${GITHUB_REPOSITORY}/pull/${PR_NUMBER}"
+            
+            # Build the check summary with full changelog
+            CHECK_SUMMARY="## Semver Impact
+
+          ${BUMP_BADGE}
+
+          <details>
+          <summary>📋 Changelog Preview</summary>
+
+          This is how your changes will appear in the changelog.
+          Entries from this PR are highlighted with a left border (blockquote style).
+
+          ---
+
+          ${CHANGELOG}
+
+          ---
+
+          </details>
+
+          [→ View PR #${PR_NUMBER}](${PR_URL})"
+
+            # Create check run via GitHub API using jq for safe JSON construction
             echo "Creating check run..."
-            gh api -X POST \
+            JSON_PAYLOAD=$(jq -n \
+              --arg name "Changelog" \
+              --arg head_sha "$HEAD_SHA" \
+              --arg details_url "$DETAILS_URL" \
+              --arg title "$BUMP_SHORT" \
+              --arg summary "$CHECK_SUMMARY" \
+              '{
+                name: $name,
+                head_sha: $head_sha,
+                status: "completed",
+                conclusion: "neutral",
+                details_url: $details_url,
+                output: {
+                  title: $title,
+                  summary: $summary
+                }
+              }')
+
+            gh api --method POST \
+              -H "Accept: application/vnd.github+json" \
+              -H "X-GitHub-Api-Version: 2022-11-28" \
               "repos/$GITHUB_REPOSITORY/check-runs" \
-              -f name="Changelog" \
-              -f head_sha="${{ github.event.pull_request.head.sha || github.sha }}" \
-              -f status="completed" \
-              -f conclusion="neutral" \
-              -f output[title]="$BUMP_SHORT" \
-              -f output[summary]="$CHANGELOG"
+              --input - <<< "$JSON_PAYLOAD"
             
             echo "✓ Check run created"
             
             # 2. Write to job summary
-            PR_URL="${GITHUB_SERVER_URL}/${GITHUB_REPOSITORY}/pull/${PR_NUMBER}"
-            
             cat >> $GITHUB_STEP_SUMMARY << CRAFT_CHANGELOG_SUMMARY_END
           # Changelog Preview for PR #${PR_NUMBER}
 

From 534f1bd48911ee097f171d102d3a94b323961b36 Mon Sep 17 00:00:00 2001
From: Burak Yigit Kaya <byk@sentry.io>
Date: Thu, 15 Jan 2026 17:52:17 +0000
Subject: [PATCH 4/8] fix: Simplify check run summary formatting

Remove duplicate 'Semver Impact' header - it's already in the title
Remove extra explanatory text to clean up the display
---
 .github/workflows/changelog-preview.yml | 13 ++-----------
 1 file changed, 2 insertions(+), 11 deletions(-)

diff --git a/.github/workflows/changelog-preview.yml b/.github/workflows/changelog-preview.yml
index 6cf1d029..bf928687 100644
--- a/.github/workflows/changelog-preview.yml
+++ b/.github/workflows/changelog-preview.yml
@@ -175,23 +175,14 @@ jobs:
             DETAILS_URL="${GITHUB_SERVER_URL}/${GITHUB_REPOSITORY}/actions/runs/${GITHUB_RUN_ID}"
             PR_URL="${GITHUB_SERVER_URL}/${GITHUB_REPOSITORY}/pull/${PR_NUMBER}"
             
-            # Build the check summary with full changelog
-            CHECK_SUMMARY="## Semver Impact
-
-          ${BUMP_BADGE}
+            # Build the check summary with full changelog (simpler format)
+            CHECK_SUMMARY="${BUMP_BADGE}
 
           <details>
           <summary>📋 Changelog Preview</summary>
 
-          This is how your changes will appear in the changelog.
-          Entries from this PR are highlighted with a left border (blockquote style).
-
-          ---
-
           ${CHANGELOG}
 
-          ---
-
           </details>
 
           [→ View PR #${PR_NUMBER}](${PR_URL})"

From 28a787bf33fdfd7910f00250c51d0013d6a60345 Mon Sep 17 00:00:00 2001
From: Burak Yigit Kaya <byk@sentry.io>
Date: Thu, 15 Jan 2026 17:56:35 +0000
Subject: [PATCH 5/8] refactor: Switch from Check Runs API to Commit Status API

The Check Runs API was causing grouping issues in the GitHub UI where
the 'Changelog' check was being grouped under other workflows like
'CodeQL'. The Commit Status API provides a cleaner solution:

- Status appears independently in the checks list (not grouped)
- Simpler API with fewer parameters
- Works reliably with GITHUB_TOKEN
- Still shows semver impact prominently

Changes:
- Replace check runs creation with commit status creation
- Update permissions from checks:write to statuses:write
- Update all documentation references
- Simplify implementation (no need for complex JSON with jq)
- Full changelog still available in Actions job summary
---
 .github/workflows/changelog-preview.yml | 59 +++++++------------------
 docs/src/content/docs/github-actions.md | 29 ++++++------
 2 files changed, 31 insertions(+), 57 deletions(-)

diff --git a/.github/workflows/changelog-preview.yml b/.github/workflows/changelog-preview.yml
index bf928687..a7d2a5d3 100644
--- a/.github/workflows/changelog-preview.yml
+++ b/.github/workflows/changelog-preview.yml
@@ -9,7 +9,7 @@ on:
   # 1. Grant required permissions:
   #    - contents: read        (to checkout repo and read git history)
   #    - pull-requests: write  (to post/update PR comments in comment mode)
-  #    - checks: write         (to create check runs in check run mode)
+  #    - statuses: write       (to create commit statuses in status check mode)
   #
   # 2. Inherit secrets:
   #    - secrets: inherit      (ensures caller's GITHUB_TOKEN is used)
@@ -29,11 +29,11 @@ on:
   #       uses: getsentry/craft/.github/workflows/changelog-preview.yml@v2
   #       secrets: inherit
   #
-  # Example caller workflow (check run mode):
+  # Example caller workflow (status check mode):
   #
   #   permissions:
   #     contents: read
-  #     checks: write
+  #     statuses: write
   #
   #   jobs:
   #     changelog-preview:
@@ -67,7 +67,7 @@ on:
 permissions:
   contents: read
   pull-requests: write # For comment mode
-  checks: write # For check run mode
+  statuses: write # For status check mode
 
 jobs:
   preview:
@@ -165,55 +165,28 @@ jobs:
             *) BUMP_SHORT="Semver impact: ⚪ None" ;;
           esac
 
-          # Determine mode: use check run mode when comment is false OR when running internally (no input)
+          # Determine mode: use status check mode when comment is false OR when running internally (no input)
           USE_COMMENT_MODE="${{ inputs.comment }}"
           if [[ "$USE_COMMENT_MODE" == "false" ]] || [[ -z "$USE_COMMENT_MODE" ]]; then
-            # Check run mode (new feature or internal dogfooding)
-            echo "Using check run mode..."
+            # Status check mode (new feature or internal dogfooding)
+            echo "Using status check mode..."
             
             HEAD_SHA="${{ github.event.pull_request.head.sha || github.sha }}"
-            DETAILS_URL="${GITHUB_SERVER_URL}/${GITHUB_REPOSITORY}/actions/runs/${GITHUB_RUN_ID}"
+            TARGET_URL="${GITHUB_SERVER_URL}/${GITHUB_REPOSITORY}/actions/runs/${GITHUB_RUN_ID}"
             PR_URL="${GITHUB_SERVER_URL}/${GITHUB_REPOSITORY}/pull/${PR_NUMBER}"
             
-            # Build the check summary with full changelog (simpler format)
-            CHECK_SUMMARY="${BUMP_BADGE}
-
-          <details>
-          <summary>📋 Changelog Preview</summary>
-
-          ${CHANGELOG}
-
-          </details>
-
-          [→ View PR #${PR_NUMBER}](${PR_URL})"
-
-            # Create check run via GitHub API using jq for safe JSON construction
-            echo "Creating check run..."
-            JSON_PAYLOAD=$(jq -n \
-              --arg name "Changelog" \
-              --arg head_sha "$HEAD_SHA" \
-              --arg details_url "$DETAILS_URL" \
-              --arg title "$BUMP_SHORT" \
-              --arg summary "$CHECK_SUMMARY" \
-              '{
-                name: $name,
-                head_sha: $head_sha,
-                status: "completed",
-                conclusion: "neutral",
-                details_url: $details_url,
-                output: {
-                  title: $title,
-                  summary: $summary
-                }
-              }')
-
+            # Create commit status via GitHub API
+            echo "Creating commit status..."
             gh api --method POST \
               -H "Accept: application/vnd.github+json" \
               -H "X-GitHub-Api-Version: 2022-11-28" \
-              "repos/$GITHUB_REPOSITORY/check-runs" \
-              --input - <<< "$JSON_PAYLOAD"
+              "repos/$GITHUB_REPOSITORY/statuses/$HEAD_SHA" \
+              -f state="success" \
+              -f context="Changelog" \
+              -f description="$BUMP_SHORT" \
+              -f target_url="$TARGET_URL"
             
-            echo "✓ Check run created"
+            echo "✓ Commit status created"
             
             # 2. Write to job summary
             cat >> $GITHUB_STEP_SUMMARY << CRAFT_CHANGELOG_SUMMARY_END
diff --git a/docs/src/content/docs/github-actions.md b/docs/src/content/docs/github-actions.md
index dd2f0ad5..40b06793 100644
--- a/docs/src/content/docs/github-actions.md
+++ b/docs/src/content/docs/github-actions.md
@@ -142,11 +142,11 @@ jobs:
 
 ### Inputs
 
-| Input               | Description                                                                  | Default  |
-| ------------------- | ---------------------------------------------------------------------------- | -------- |
-| `working-directory` | Directory to run Craft in (relative to repo root)                            | `.`      |
-| `craft-version`     | Version of Craft to use (tag or "latest")                                    | `latest` |
-| `comment`           | Post changelog as PR comment (true) or as check run with job summary (false) | `true`   |
+| Input               | Description                                                                      | Default  |
+| ------------------- | -------------------------------------------------------------------------------- | -------- |
+| `working-directory` | Directory to run Craft in (relative to repo root)                                | `.`      |
+| `craft-version`     | Version of Craft to use (tag or "latest")                                        | `latest` |
+| `comment`           | Post changelog as PR comment (true) or as commit status with job summary (false) | `true`   |
 
 ### Output Modes
 
@@ -185,9 +185,9 @@ permissions:
   pull-requests: write
 ```
 
-#### Check Run Mode
+#### Status Check Mode
 
-Creates a neutral check run with detailed output and writes to the Actions job summary:
+Creates a commit status with the semver impact and writes the full changelog to the Actions job summary:
 
 ```yaml
 jobs:
@@ -202,12 +202,13 @@ jobs:
 
 - Minimal notification noise
 - Cleaner PR interface
-- Semver impact visible in checks section
-- Full changelog available in check details and Actions summary
+- Semver impact visible in status checks section
+- Full changelog available in Actions job summary
+- Status appears independently (not grouped with other checks)
 
 **Cons:**
 
-- Requires clicking through to see full changelog
+- Requires clicking through to Actions run to see full changelog
 - Less immediate visibility than comment
 
 **Required permissions:**
@@ -215,11 +216,11 @@ jobs:
 ```yaml
 permissions:
   contents: read
-  checks: write
+  statuses: write
 ```
 
 :::tip
-Craft itself uses check run mode to avoid notification noise. You can see it in action on any PR in the [getsentry/craft repository](https://github.com/getsentry/craft/pulls).
+Craft itself uses status check mode to avoid notification noise. You can see it in action on any PR in the [getsentry/craft repository](https://github.com/getsentry/craft/pulls).
 :::
 
 ### Pinning a Specific Version
@@ -302,7 +303,7 @@ The workflow requires specific permissions and secrets to function correctly:
 
 - `contents: read` - Allows the workflow to checkout your repository and read git history for changelog generation
 - `pull-requests: write` - Required for comment mode (default) to post and update comments on pull requests
-- `checks: write` - Required for check run mode (when `comment: false`) to create check runs
+- `statuses: write` - Required for status check mode (when `comment: false`) to create commit statuses
 
 **Secrets**:
 
@@ -315,7 +316,7 @@ The workflow requires specific permissions and secrets to function correctly:
 :::note[Why are these permissions needed?]
 GitHub Actions reusable workflows use permission intersection - the final permissions are the intersection of what the caller grants and what the workflow declares. By explicitly declaring these permissions in your workflow file, you ensure the workflow can access your repository and perform the necessary actions, even for private repositories.
 
-Note: You only need `pull-requests: write` for comment mode OR `checks: write` for check run mode, not both. However, it's safe to grant both permissions if you're unsure which mode you'll use.
+Note: You only need `pull-requests: write` for comment mode OR `statuses: write` for status check mode, not both. However, it's safe to grant both permissions if you're unsure which mode you'll use.
 :::
 
 ## Skipping Changelog Entries

From ac8a57de29550979c071400385a0c2569887739f Mon Sep 17 00:00:00 2001
From: Burak Yigit Kaya <byk@sentry.io>
Date: Thu, 15 Jan 2026 17:57:42 +0000
Subject: [PATCH 6/8] fix: Remove emojis from status description

Commit Status API doesn't support 4-byte Unicode (emojis).
Keep emojis in BUMP_BADGE for display, but use plain text
for the status description field.
---
 .github/workflows/changelog-preview.yml | 22 +++++++++++++++++-----
 1 file changed, 17 insertions(+), 5 deletions(-)

diff --git a/.github/workflows/changelog-preview.yml b/.github/workflows/changelog-preview.yml
index a7d2a5d3..18981b16 100644
--- a/.github/workflows/changelog-preview.yml
+++ b/.github/workflows/changelog-preview.yml
@@ -157,12 +157,24 @@ jobs:
             *) BUMP_BADGE="⚪ **None** (no version bump detected)" ;;
           esac
 
-          # Create short description with emoji for check run title
+          # Create descriptions for status check (no emoji support in Commit Status API)
           case "$BUMP_TYPE" in
-            major) BUMP_SHORT="Semver impact: 🔴 Major" ;;
-            minor) BUMP_SHORT="Semver impact: 🟡 Minor" ;;
-            patch) BUMP_SHORT="Semver impact: 🟢 Patch" ;;
-            *) BUMP_SHORT="Semver impact: ⚪ None" ;;
+            major) 
+              BUMP_SHORT="Semver impact: Major"
+              BUMP_EMOJI="🔴"
+              ;;
+            minor) 
+              BUMP_SHORT="Semver impact: Minor"
+              BUMP_EMOJI="🟡"
+              ;;
+            patch) 
+              BUMP_SHORT="Semver impact: Patch"
+              BUMP_EMOJI="🟢"
+              ;;
+            *) 
+              BUMP_SHORT="Semver impact: None"
+              BUMP_EMOJI="⚪"
+              ;;
           esac
 
           # Determine mode: use status check mode when comment is false OR when running internally (no input)

From 23fd530b1058758f5aedf4c639b06ec44990a8f8 Mon Sep 17 00:00:00 2001
From: Burak Yigit Kaya <byk@sentry.io>
Date: Thu, 15 Jan 2026 18:39:41 +0000
Subject: [PATCH 7/8] fix: Update commit status naming and description
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Change context from 'Changelog' to 'Changelog Preview / Semver Impact'
- Simplify description to just the bump type (e.g., 'Minor')
- Remove 'Semver impact:' prefix since it's now in the context name

Result: Status shows as 'Changelog Preview / Semver Impact — Minor'
---
 .github/workflows/changelog-preview.yml | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/.github/workflows/changelog-preview.yml b/.github/workflows/changelog-preview.yml
index 18981b16..e6d81cc8 100644
--- a/.github/workflows/changelog-preview.yml
+++ b/.github/workflows/changelog-preview.yml
@@ -160,19 +160,19 @@ jobs:
           # Create descriptions for status check (no emoji support in Commit Status API)
           case "$BUMP_TYPE" in
             major) 
-              BUMP_SHORT="Semver impact: Major"
+              BUMP_SHORT="Major"
               BUMP_EMOJI="🔴"
               ;;
             minor) 
-              BUMP_SHORT="Semver impact: Minor"
+              BUMP_SHORT="Minor"
               BUMP_EMOJI="🟡"
               ;;
             patch) 
-              BUMP_SHORT="Semver impact: Patch"
+              BUMP_SHORT="Patch"
               BUMP_EMOJI="🟢"
               ;;
             *) 
-              BUMP_SHORT="Semver impact: None"
+              BUMP_SHORT="None"
               BUMP_EMOJI="⚪"
               ;;
           esac
@@ -194,7 +194,7 @@ jobs:
               -H "X-GitHub-Api-Version: 2022-11-28" \
               "repos/$GITHUB_REPOSITORY/statuses/$HEAD_SHA" \
               -f state="success" \
-              -f context="Changelog" \
+              -f context="Changelog Preview / Semver Impact" \
               -f description="$BUMP_SHORT" \
               -f target_url="$TARGET_URL"
             

From 1486a4411befb9447c5b70b20cd6befbc2cc7feb Mon Sep 17 00:00:00 2001
From: Burak Yigit Kaya <byk@sentry.io>
Date: Thu, 15 Jan 2026 20:27:56 +0000
Subject: [PATCH 8/8] Apply suggestion from @BYK

---
 docs/src/content/docs/github-actions.md | 1 -
 1 file changed, 1 deletion(-)

diff --git a/docs/src/content/docs/github-actions.md b/docs/src/content/docs/github-actions.md
index 40b06793..a2772199 100644
--- a/docs/src/content/docs/github-actions.md
+++ b/docs/src/content/docs/github-actions.md
@@ -204,7 +204,6 @@ jobs:
 - Cleaner PR interface
 - Semver impact visible in status checks section
 - Full changelog available in Actions job summary
-- Status appears independently (not grouped with other checks)
 
 **Cons:**