clerk/Break Check

Detect API breaking changes in TypeScript packages on every PR.

Trust Signals

Scorecard Score: not yet scored
Maintenance Recency: Activelast commit Jul 3, 2026
License: MIT

Pinned Snippet

workflow.ymlSHA-pinned

uses: clerk/break-check@92be9cc726c848b9567c7b869e9b11dc761ddd6e # v0.6.0

tags can be moved; commit SHAs can't. why a SHA?

Inputs

name	description	required	default
config-path	Path to break-check.config.json, relative to the repository root.	no	break-check.config.json
base-ref	Git ref or commit SHA to compare against. Defaults to the pull request base SHA (`github.event.pull_request.base.sha`) so PRs are diffed against the exact commit they were opened against, not the moving tip of the base branch.	no	${{ github.event.pull_request.base.sha \|\| github.base_ref }}
head-ref	Git ref or commit SHA to treat as the "current" side of the diff. Defaults to the pull request head SHA (`github.event.pull_request.head.sha`) so the comparison is pinned to the exact commits the PR introduces, not the `refs/pull/N/merge` ref that `actions/checkout` resolves by default. That merge ref is the PR head merged into the moving tip of the base branch, so it leaks unrelated base-branch changes into the report once the base branch advances. When empty (non pull_request events), the action builds the checked-out workspace as-is.	no	${{ github.event.pull_request.head.sha }}
setup-command	Shell command break-check runs inside both the base-ref checkout and the current checkout to install dependencies and build .d.ts files.	no	pnpm install --frozen-lockfile && pnpm build
break-check-version	Version of @clerk/break-check to fetch with `npx`. Requires >= 0.1.1, since this revision calls `detect --json-output`. The default `latest` resolves to a compatible version.	no	latest
baseline-artifact-name	Name of a baseline snapshot artifact uploaded from a push-to-`base-ref` workflow. When set, the Action downloads the most recent matching artifact instead of rebuilding `base-ref`. Falls back to the worktree rebuild if no usable artifact is found. Requires `actions:read` on `github-token` (the default `github.token` has it).	no	""
baseline-max-age	Maximum age, in hours, for a downloaded baseline artifact before the Action falls back to a fresh worktree rebuild. Default unset (no maximum). Only applies when `baseline-artifact-name` is set.	no	""
comment	Post (or update) a PR comment with the report.	no	true
report-artifact-name	Name for the uploaded report artifact. Artifact names are immutable and global to a workflow run, so when this Action runs more than once per run (a matrix, or per-package jobs) the default name collides and the second upload fails. Give each invocation a distinct name, e.g. append the matrix package name: `break-check-report-pkg-a`. (The runner template-parses expression syntax anywhere in this manifest, so an expression cannot be written literally here.)	no	break-check-report
fail-on-breaking	Fail the workflow when breaking changes are detected.	no	false
policy-mode	Enforce the break-check config from the base ref instead of the PR head. Without this, a PR can edit its own break-check.config.json (drop the changed package, add an `acknowledgedChanges` entry, widen `ignoreSubpaths`/`resolvableSpecifiers`) to suppress detection of its own breaking change. With policy-mode on, the config is taken from the base ref before the diff runs, so a config change only takes effect once it has landed on the base branch. Recommended when this Action is a required merge gate. A base ref that has no config yet (the PR introducing break-check) falls back to the PR config.	no	false
anthropic-api-key	Anthropic API key. When set, break-check routes the rule-based diff through Claude for a second opinion: it escalates changes the rule pass under-classified and adds a migration hint per breaking change. By default the AI only records its breaking->non-breaking downgrades as suggestions and cannot clear a real break; turn `ai.applyDowngrades` on in break-check.config.json to act on them. Leave empty to run the deterministic rule-based diff only. Always pass this from a secret, never inline.	no	""
github-token	Token used to read existing comments and post the report.	no	${{ github.token }}

Outputs

name	description
has-breaking-changes	true if break-check detected at least one breaking change.
report-path	Path to the generated markdown report.