[SarahSoutoul]

What does this solve? What changed?

DOCS-12297 needs a stable-release sender for the add-auth eval receiver in clerk/clerk-evals.

This is the CLI-release follow-up to DOCS-12112 and clerk-evals#73, which added evals for clerk/skills updates but did not add the stable CLI-release trigger.

• After stable npm publish succeeds, send clerk_cli_released with the exact version without waiting for npm's latest tag. The paired eval receiver checks clerk@latest before evaluating.
• Exclude canary and snapshot releases. Use a dedicated CLERK_EVALS_DISPATCH_TOKEN; keep the default GITHUB_TOKEN read-only.
• Fail the dispatch job if GitHub rejects the event, so release failure notification can surface sending failures. If npm never reports the version as latest, the eval receiver reports that separately.
• Document the job and credential in the release guide.

Deadline

No fixed deadline. Merge clerk/clerk-evals#78 first, then this sender. A release dispatch sent before the receiver is live would not be replayed.

Other resources

• DOCS-12297
• clerk/clerk-evals#78 — paired eval receiver

Pre-merge checklist

• Focused dispatch tests pass locally (3 tests).
• Review CI and the paired receiver.
• Create a dedicated fine-grained token with Contents: read and write on only clerk/clerk-evals, then add it to clerk/cli as the Actions secret CLERK_EVALS_DISPATCH_TOKEN. Confirm it can send repository dispatches; do not share its value in the PR.

Post-merge checklist

• Observe one stable release, its dispatch, and the corresponding eval result at the published version.
• Confirm a repeated event is harmless and canary/snapshot releases do not dispatch.

[changeset-bot]

⚠️ No Changeset found

Latest commit: 3acf29c

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Organization UI
• Review profile: ASSERTIVE
• Plan: Team
• Run ID: efd69c9a-9200-437f-a31d-bea170f2cf87

📥 Commits

Reviewing files that changed from the base of the PR and between 2133e7e and 3acf29c.

📒 Files selected for processing: 4

• .github/workflows/release.yml
• docs/releasing.md
• scripts/dispatch-evals.test.ts
• scripts/dispatch-evals.ts

🔗 Linked repositories identified

CodeRabbit considers these linked repositories for cross-repo context during reviews:

• clerk/clerk_go (manual)
• clerk/dashboard (manual)
• clerk/accounts (manual)
• clerk/backoffice (manual)
• clerk/clerk (manual)
• clerk/clerk-docs (manual)
• clerk/cloudflare-workers (manual)

Included review availability: This review used your included allowance. 9 included reviews remain after this review. Your included PR review attempts over the past 7 days set your current allowance at 10 reviews per hour.

📝 Walkthrough

The release workflow now dispatches stable CLI versions to clerk-evals after versioning and npm publishing succeed. The dispatch script validates the version, requires a token, and reports API errors. Dispatch failures are included in stable-release failure notification. The release documentation describes the dispatch event and token, and tests cover validation and request behavior.

Priority: ➖ Normal

Estimated code review effort: 3 (Moderate) | ~20 minutes

Suggested reviewers: wyattjoh

Merge Risk: ⚪ Minimal · up to 3acf2

No code issue identified here prevents merging. The receiver must be live and the dedicated dispatch token configured before the first stable release that sends the event.

Pre-merge checks: 4 · 1

Failed checks: 1 warning

Check name	Status	Explanation	Resolution
Docstring Coverage		Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 2 functions across 2 files. (2 skipped: 2 …	Write docstrings for the functions missing them to satisfy the coverage threshold.

Passed checks: 4 passed

Check name	Status	Explanation
Title check		The title clearly and concisely describes dispatching add-auth evaluations after stable Clerk CLI releases.
Description check		The description directly explains the stable-release dispatch, excluded release types, credentials, failure handling, documentation, and validation status.
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.

Full details: Docstring Coverage

Explanation

Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 2 functions across 2 files. (2 skipped: 2 unsupported.)

Resolution

Write docstrings for the functions missing them to satisfy the coverage threshold.

• Fix all pre-merge checks with AI

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

_{Comment @coderabbitai help to get the list of available commands.}

[SarahSoutoul]

One detail worth calling out against DOCS-12297: the ticket says to dispatch once the release is available as clerk@latest, but this PR dispatches as soon as the stable npm publish succeeds. That's intentional as the paired eval receiver waits for the exact released version to become latest before running, and fails visibly if it doesn't. This keeps npm propagation delays from making the CLI release itself look broken while still preventing an eval against the wrong version. @manovotny

[manovotny]

@SarahSoutoul agreed. Stable publishes don't pass --tag, so npm marks the version latest on publish, and the receiver's 10-minute wait covers the registry catching up.

[manovotny]

This job sends clerk_cli_released, which is already a generic event. The job and script names describe what clerk-evals does with it today, not what this workflow does.

clerk/skills has the same kind of sender, and it's named after its event: dispatch-skills-updated.yml and dispatch-skills-update.mjs. It sends one event to clerk, dashboard, and clerk-evals, so adding a receiver is a one-line change.

Could we match that here? dispatch-cli-released for the job and scripts/dispatch-cli-released.ts for the script, with the step name and the docs/releasing.md paragraph to match.

Same idea for the secret while it doesn't exist yet: CLERK_CLI_DISPATCH_TOKEN would follow the CLERK_SKILLS_DISPATCH_TOKEN naming. Your call on that one.

That way none of it is tied to evals, and anything interested in CLI releases can use this.

[manovotny]

If publishing succeeds and the dispatch fails, this posts "Stable release failed" while notify-stable-success still announces the release. An expired token is enough to trigger it.

Maybe give the dispatch its own failure alert instead, like the notify-failure job in the skills sender? Adding the dispatch to notify-stable-success's needs would also fix the mismatch, but then an expired token would hold back the release announcement.

[manovotny]

sendCliReleaseDispatch already checks this, and the test covers it there.

Suggested change

if (!token) throw new Error("CLERK_EVALS_DISPATCH_TOKEN is not configured");