feat: migrate to Craft #1232

betegon · 2026-01-07T13:17:43Z

This PR migrates our release management from Changesets to Craft, Sentry's release tool.

Why Craft?

No changeset files: No need to create/commit .changeset/*.md files for each PR
Auto-versioning: Version bumps determined automatically from conventional commits
Better changelogs: Auto-generated with scope grouping and category organization
PR previews: Changelog preview comments on every PR
Simpler workflow: All release info lives in commit messages, not extra files

Changes

Removed

@changesets/cli and @svitejs/changesets-changelog-github-compact dependencies
changeset:* scripts from root package.json
prepare-publish.yml workflow

Added

.craft.yml - Craft configuration with auto versioning and npm/github targets
scripts/bump-version.sh - Version bump script called by Craft
.github/release.yml - Changelog categories for conventional commits
.github/workflows/release.yml - Craft release workflow
.github/workflows/changelog-preview.yml - PR changelog previews
Updated
.github/workflows/build.yml - Trigger on release/** branches
.github/workflows/publish.yml - Trigger on changelog changes instead of changeset commit messages
Contributor docs updated to explain conventional commits

New Release Flow

Contributors use conventional commits (feat:, fix:, docs:, etc.)
PRs show automatic changelog preview comments
Maintainer triggers "Release" workflow → Craft creates release branch
After merge, publish workflow handles NPM, Docker, and Electron releases

Tested locally:

- Remove @changesets/cli and @svitejs/changesets-changelog-github-compact - Remove changeset:add, changeset:consume, changeset:publish scripts - Delete prepare-publish.yml workflow

- Add .craft.yml with auto versioning and changelog generation - Add scripts/bump-version.sh to update package versions - Add .github/release.yml for conventional commit changelog categories Craft will automatically determine version bumps from conventional commits (feat: → minor, fix: → patch, feat!: → major).

- Update build.yml to trigger on release/** branches - Add release.yml using Craft's reusable release workflow - Update publish.yml to trigger on changelog changes - Add changelog-preview.yml for PR changelog comments

- Update changesets.mdx to explain conventional commits - Update releases.mdx to document new Craft release process

vercel · 2026-01-07T13:17:48Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Review	Updated (UTC)
spotlightjs	Ready	Preview, Comment	Jan 9, 2026 7:38pm

github-actions · 2026-01-07T13:18:03Z

Semver Impact of This PR

🟡 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 ✨

Migrate to Craft by betegon in #1232

Added a dynamic header for dragbar by MathurAditya724 in #1223
Better error message display by MathurAditya724 in #1222

Bug Fixes 🐛

Ui

Add validation guards to WebVitalsDetail to prevent crashes by BYK in #1243
Handle null/undefined span.description safely by BYK in #1239

Other

(sentry) Upload and use source maps for all build targets by BYK in #1241
Updated react-router-dom version to latest by MathurAditya724 in #1245
Add error handling for base64 decode operations by BYK in #1237
Silence non-fixable Sentry errors by BYK in #1242
Add null safety to WebVitals comparators by BYK in #1238
Add null check for itemHeader in processEnvelope by BYK in #1233
Shiki theme in light mode by MathurAditya724 in #1230

Documentation 📚

Website

Add feedback note for Spotlight SDK in documentation by MathurAditya724 in #1228
Add NextJS guide by betegon in #1129

Other

Add section for the spotlight sdk by MathurAditya724 in #1227

Build / dependencies / internal 🔧

(deps) Bump @modelcontextprotocol/sdk from 1.24.3 to 1.25.2 by dependabot in #1234
Add workflow to notify issues on release by betegon in #1236
Using the param instead of calling a function by MathurAditya724 in #1224

Other

Node 24.x support by BYK in #1235
Vite windows deny bypass by BYK in #1229
Qs security vulnerability fix by BYK in #1226
Dependency security updates by BYK in #1225
Event origin badges ui by BYK in #1221

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

.github/workflows/changelog-preview.yml

+    name: Preview Changelog
+    uses: getsentry/craft/.github/workflows/changelog-preview.yml@v2
+    secrets: inherit


To fix the problem, add an explicit permissions block that restricts the default GITHUB_TOKEN access for this workflow. Because this workflow is only orchestrating a reusable workflow and does not itself perform any direct repository mutations, a safe and conservative default is contents: read. This adheres to the principle of least privilege while still allowing typical read operations (like fetching code) if needed by the reusable workflow.

The best way to fix this without changing existing functionality is:

Add a permissions block at the root level of .github/workflows/changelog-preview.yml, alongside name and on, so that it applies to all jobs in the workflow (including the changelog-preview job).

Set contents: read as the minimal permission. If the reusable workflow needs additional scopes (for example, pull-requests: write), those should be added there, but we will not assume extra needs beyond contents: read since we cannot see the implementation of the reusable workflow and we must avoid altering behavior more than necessary.

Concretely:

In .github/workflows/changelog-preview.yml, after the name: Changelog Preview line, insert:

permissions: contents: read

No imports or additional methods are required, as this is a YAML configuration change only.

.github/workflows/release.yml

+    name: Prepare Release
+    uses: getsentry/craft/.github/workflows/release.yml@v2
+    with:
+      version: ${{ inputs.version || 'auto' }}
+      force: ${{ inputs.force }}
+    secrets: inherit


In general, the fix is to define an explicit permissions: block that limits the GITHUB_TOKEN to the least privileges required. This can be set at the workflow root (applies to all jobs unless overridden) or for the specific job. Since this workflow only defines one job, adding a root-level permissions: block is simple and avoids changing behavior of the reusable workflow beyond constraining the token permissions.

The best minimal, non-breaking change is to add a workflow-level permissions: block immediately after the name: Release line. If we are unsure exactly which fine-grained permissions the reusable workflow needs, a conservative and still significantly safer default is contents: read, which is GitHub’s recommended minimal baseline. If later we discover that the reusable workflow requires additional scopes (e.g., contents: write, pull-requests: write), those can be added explicitly. For now, we will follow the CodeQL suggestion to define an explicit minimal starting point and use contents: read.

Concretely, edit .github/workflows/release.yml and insert:

permissions: contents: read

between the existing name: Release line and the on: block. No imports or additional definitions are needed since this is pure YAML configuration.

.github/workflows/publish.yml

.github/workflows/post-release.yml

- Update .craft.yml with proper npm and github targets - Simplify publish.yml to only handle Docker and Electron - NPM publishing and GitHub releases now handled by getsentry/publish - Trigger post-release workflow on release:published event The release flow is now: 1. release.yml -> craft prepare -> creates publish issue 2. getsentry/publish -> craft publish -> npm + GitHub release 3. publish.yml -> Docker tagging + Electron signing

BYK

Nice! Follow up:

Also remove that annoying PR template please
Me to do NPM org/token shenenigans

.github/workflows/publish.yml

.github/workflows/release.yml

packages/website/src/content/docs/docs/contribute/commits.mdx

packages/website/src/content/docs/docs/contribute/releases.mdx

.craft.yml

Explains how the Craft + getsentry/publish release flow works, including the Post-Release workflow for Docker and Electron.

- Introduced a new GitHub Actions workflow for building the Electron app on macOS. - Added steps for setting up dependencies, downloading the Electron build, and validating the build files. - Implemented storage of Electron binaries as artifacts for future use. - Updated the .craft.yml to include tagging for Electron binaries in the release process. - Removed the obsolete post-release workflow file.

BYK

Let's also delete the following:

BYK · 2026-01-10T01:54:55Z

.github/workflows/release.yml

+    uses: getsentry/craft/.github/workflows/release.yml@v2
+    with:
+      version: ${{ inputs.version }}
+      force: ${{ inputs.force }}
+    secrets: inherit


We need the release to be done by the release bot and the way to use that is like here: https://github.com/getsentry/sentry-wizard/blob/3c21d283fbfc5ce72cac137022102e911a86a290/.github/workflows/release.yml

BYK · 2026-01-10T01:55:21Z

.github/RELEASE_FLOW.md

Do we really need this file?

BYK · 2026-01-10T01:57:15Z

.craft.yml

+  - name: docker
+    source: ghcr.io/getsentry/spotlight
+    target: ghcr.io/getsentry/spotlight


Not sure what this is supposed to do?

BYK · 2026-01-10T01:58:53Z

FYI I added the release/** branches to protection rules and allowed the signing secrets to be used from those branches (through environment: production)

betegon added 4 commits January 7, 2026 14:09

chore: remove changesets dependencies and workflows

f5754ad

- Remove @changesets/cli and @svitejs/changesets-changelog-github-compact - Remove changeset:add, changeset:consume, changeset:publish scripts - Delete prepare-publish.yml workflow

ci: update GitHub Actions for Craft releases

e850d38

- Update build.yml to trigger on release/** branches - Add release.yml using Craft's reusable release workflow - Update publish.yml to trigger on changelog changes - Add changelog-preview.yml for PR changelog comments

docs: update contributor docs for Craft workflow

f518553

- Update changesets.mdx to explain conventional commits - Update releases.mdx to document new Craft release process

betegon deployed to Preview January 7, 2026 13:17 — with GitHub Actions Active

github-advanced-security bot found potential problems Jan 7, 2026

View reviewed changes

sentry bot reviewed Jan 7, 2026

View reviewed changes

.github/workflows/publish.yml Show resolved Hide resolved

cursor bot reviewed Jan 7, 2026

View reviewed changes

.github/workflows/publish.yml Outdated Show resolved Hide resolved

.github/workflows/post-release.yml Outdated Show resolved Hide resolved

betegon marked this pull request as draft January 7, 2026 13:26

Merge branch 'main' into feat/migrate-to-craft

21675af

betegon deployed to Preview January 7, 2026 19:00 — with GitHub Actions Active

remove spacing

ce4339b

betegon deployed to Preview January 7, 2026 19:17 — with GitHub Actions Active

betegon added 2 commits January 7, 2026 20:20

remove spacing

22d75f7

remove default config

42d2991

betegon deployed to Preview January 7, 2026 19:44 — with GitHub Actions Active

betegon deployed to Preview January 7, 2026 20:36 — with GitHub Actions Active

BYK requested changes Jan 7, 2026

View reviewed changes

docs: add release flow documentation

ed2a94f

Explains how the Craft + getsentry/publish release flow works, including the Post-Release workflow for Docker and Electron.

betegon deployed to Preview January 8, 2026 14:39 — with GitHub Actions Active

change action name

3c9e98e

betegon deployed to Preview January 8, 2026 14:52 — with GitHub Actions Active

Merge branch 'main' into feat/migrate-to-craft

95d2a0e

betegon deployed to Preview January 9, 2026 17:48 — with GitHub Actions Active

betegon added 3 commits January 9, 2026 20:23

docs

ca733ce

improve docs

2c810ce

mention publish

7f00ff0

betegon deployed to Preview January 9, 2026 19:31 — with GitHub Actions Active

betegon added 2 commits January 9, 2026 20:32

more docs

e7e989b

remove redundant code and simplify update version

39dc3f5

betegon deployed to Preview January 9, 2026 19:37 — with GitHub Actions Active

betegon marked this pull request as ready for review January 9, 2026 19:37

betegon requested a review from BYK January 9, 2026 19:45

BYK requested changes Jan 10, 2026

View reviewed changes

@@ -3,6 +3,8 @@
             # https://getsentry.github.io/craft/
             name: Changelog Preview
+            permissions:
+              contents: read
             on:
               pull_request:
                 types: [opened, synchronize, reopened, edited, labeled, unlabeled]

Uh oh!

feat: migrate to Craft #1232

Are you sure you want to change the base?

feat: migrate to Craft #1232

Uh oh!

Conversation

betegon commented Jan 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Why Craft?

Changes

Removed

Added

New Release Flow

Uh oh!

vercel bot commented Jan 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Jan 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Semver Impact of This PR

📋 Changelog Preview

New Features ✨

Bug Fixes 🐛

Ui

Other

Documentation 📚

Website

Other

Build / dependencies / internal 🔧

Other

Uh oh!

Check warning

Copilot Autofix

Check warning

Copilot Autofix

Uh oh!

Uh oh!

Uh oh!

BYK left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

BYK left a comment

Choose a reason for hiding this comment

Uh oh!

BYK Jan 10, 2026

Choose a reason for hiding this comment

Uh oh!

BYK Jan 10, 2026

Choose a reason for hiding this comment

Uh oh!

BYK Jan 10, 2026

Choose a reason for hiding this comment

Uh oh!

BYK commented Jan 10, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

betegon commented Jan 7, 2026 •

edited

Loading

vercel bot commented Jan 7, 2026 •

edited

Loading

github-actions bot commented Jan 7, 2026 •

edited

Loading