ci(repo): restore release-triggered TypeDoc sync

[SarahSoutoul]

Important

DO NOT merge this PR before the companion clerk/clerk PR is merged.

Description

After a stable package publish, dispatch clerk/clerk's docs-typedoc.yml instead of the retired clerk/clerk-docs workflow. Pass the publishing run's JavaScript commit SHA (context.sha) so TypeDoc checks out that exact repository revision. Both the normal and recovery paths mark TypeDoc as critical: its dispatch failure fails the release job visibly, while dispatch failures to dashboard and sdk-infra-workers remain warnings.

The contributor guide now links to its current path in the public docs mirror, and docs/CICD.md names clerk/clerk and clerk-docs/clerk-typedoc/ as the TypeDoc destination.

Release timing: The release workflow runs on pushes to main, but the normal TypeDoc dispatch is gated on Changesets reporting published == 'true'. A JSDoc-only merge without a package publish does not trigger TypeDoc; its changes are picked up by a later stable publish or a manual TypeDoc run. This matches the old automatic release gate.

Release announcement behavior: The TypeDoc dispatch runs before the existing Slack publish announcement. A failed TypeDoc dispatch leaves the Actions run red, but the announcement still sends when Changesets reports a publish, the run has not been canceled, and its payload was built successfully. The !cancelled() conditions bypass GitHub Actions' implicit success gate after a dispatch failure while respecting cancellation. This preserves the previous publish-announcement behavior; it does not add a TypeDoc Slack alert. The ticket requires a visible dispatch failure, not this announcement behavior.

This pairs with clerk/clerk#3474, which must merge first to accept javascript_ref. CLERK_COOKIE_PAT must have workflow-dispatch access to clerk/clerk; its repository scope still needs verification. The workflow YAML parses, the diff passes whitespace checks, and mocked failures cover every target in both dispatch paths. The end-to-end check is a production release opening a TypeDoc PR without manual dispatch.

An empty changeset is included because this is a repository workflow change with no package-facing release note.

The PR also removes an unused globby install from the PR title-linter workflow. Its dependency download was returning a registry 404 before commitlint could check the title; the title check passes after removing it.

DOCS-12215

Checklist

• Before merging, verify that CLERK_COOKIE_PAT can dispatch workflows in clerk/clerk (fine-grained PAT: clerk/clerk repository access with Actions read/write; classic PAT: repo scope and repository access).

Other

• pnpm test runs as expected. (Not run; workflow and documentation changes.)
• pnpm build runs as expected. (Not run; workflow and documentation changes.)
• (If applicable) JSDoc comments have been added or updated for any package exports. (Not applicable.)
• (If applicable) Documentation has been updated. (docs/CICD.md and docs/CONTRIBUTING.md were updated; the companion PR updates docs contributor guidance.)

Type of change

• 🐛 Bug fix
• 🌟 New feature
• 🔨 Breaking change
• 📖 Refactoring / dependency upgrade / documentation
• other:

[changeset-bot]

🦋 Changeset detected

Latest commit: 275f1b7

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 0 packages

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

Not sure what this means? Click here to learn what changesets are.

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

[vercel]

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

Project	Deployment	Actions	Updated
clerk-js-sandbox	Ready	Preview	Sep 30, 2026 8:02pm UTC
swingset	Ready	Preview	Sep 30, 2026 8:02pm UTC

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository YAML (base), Organization UI (inherited)

Review profile: ASSERTIVE

Plan: Team

Run ID: e5d9aeea-e528-4cb1-94de-3c92e51fad32

📥 Commits

Reviewing files that changed from the base of the PR and between e22a3e9 and 275f1b7.

📒 Files selected for processing (2)

• docs/CICD.md
• docs/CONTRIBUTING.md

🔗 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) → reviewed against open PR #3474 ss/fix-typedoc-workflow instead of the default branch
• clerk/clerk-docs (manual)
• clerk/cloudflare-workers (manual)
• clerk/cli (auto-detected)
• clerk/clerk-ios (auto-detected)
• clerk/clerk-android (auto-detected)

Included review availability: This review used your included allowance. 8 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

Walkthrough

The release and recovery workflows now dispatch to clerk/docs-typedoc.yml with the current commit SHA and apply per-target failure handling. Notification and Slack steps have additional run conditions. The PR-title lint workflow removes globby from its install command. An empty changeset file is added. The contribution guide and CI/CD documentation describe the docs PR and TypeDoc output path.

Priority: ⬇️ Low

Estimated code review effort: 2 (Simple) | ~12 minutes

Suggested reviewers: dstaley

Merge Risk: 🟡 Moderate · up to 275f1

Before merging, confirm that clerk/clerk main accepts javascript_ref and that CLERK_COOKIE_PAT can dispatch its workflow. Otherwise a stable release may publish packages while the TypeDoc sync fails and the release job is marked failed.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0…
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title clearly and concisely identifies the main change: restoring release-triggered TypeDoc synchronization.
Description check	✅ Passed	The description directly explains the workflow changes, dispatch behavior, dependencies, documentation updates, and required merge conditions.

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

Autopilot is currently an internal CodeRabbit preview.

---

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

[pkg-pr-new]

Open in StackBlitz

@clerk/astro

npm i https://pkg.pr.new/@clerk/astro@9988

@clerk/backend

npm i https://pkg.pr.new/@clerk/backend@9988

@clerk/chrome-extension

npm i https://pkg.pr.new/@clerk/chrome-extension@9988

@clerk/clerk-js

npm i https://pkg.pr.new/@clerk/clerk-js@9988

@clerk/electron

npm i https://pkg.pr.new/@clerk/electron@9988

@clerk/electron-passkeys

npm i https://pkg.pr.new/@clerk/electron-passkeys@9988

@clerk/eslint-plugin

npm i https://pkg.pr.new/@clerk/eslint-plugin@9988

@clerk/expo

npm i https://pkg.pr.new/@clerk/expo@9988

@clerk/expo-google-signin

npm i https://pkg.pr.new/@clerk/expo-google-signin@9988

@clerk/expo-passkeys

npm i https://pkg.pr.new/@clerk/expo-passkeys@9988

@clerk/express

npm i https://pkg.pr.new/@clerk/express@9988

@clerk/fastify

npm i https://pkg.pr.new/@clerk/fastify@9988

@clerk/hono

npm i https://pkg.pr.new/@clerk/hono@9988

@clerk/localizations

npm i https://pkg.pr.new/@clerk/localizations@9988

@clerk/mosaic

npm i https://pkg.pr.new/@clerk/mosaic@9988

@clerk/nextjs

npm i https://pkg.pr.new/@clerk/nextjs@9988

@clerk/nuxt

npm i https://pkg.pr.new/@clerk/nuxt@9988

@clerk/react

npm i https://pkg.pr.new/@clerk/react@9988

@clerk/react-router

npm i https://pkg.pr.new/@clerk/react-router@9988

@clerk/shared

npm i https://pkg.pr.new/@clerk/shared@9988

@clerk/tanstack-react-start

npm i https://pkg.pr.new/@clerk/tanstack-react-start@9988

@clerk/testing

npm i https://pkg.pr.new/@clerk/testing@9988

@clerk/ui

npm i https://pkg.pr.new/@clerk/ui@9988

@clerk/upgrade

npm i https://pkg.pr.new/@clerk/upgrade@9988

@clerk/vue

npm i https://pkg.pr.new/@clerk/vue@9988

commit: 275f1b7

[SarahSoutoul]

@wobsoriano I removed globby from the PR title-linter install because commitlint.config.ts doesn't use it. Its dependency download was returning a 404, causing the job to fail before it checked the PR title. Just wanted to flag in case I'm missing sth here?

[manovotny]

Pushed a change directly in e22a3e9.

• Replaced the retired clerk-docs workflow link in the TypeDoc section of docs/CONTRIBUTING.md, since it 404s once the mirror drops that file

[SarahSoutoul]

@manovotny I pushed a small documentation follow-up:

• Updated docs/CICD.md to show that the release dispatch updates TypeDoc files in clerk/clerk.
• Fixed the TypeDoc contributor guide link to point to its current location.

[wobsoriano]

looks straightforward 👍🏼