Clerk Docs Repo migration to clerk/clerk

[NWylynko]

Pr: https://github.com/clerk/clerk/pull/2315 must merge first

This pr brings in a script to assist with the migration of this repo in to clerk/clerk. It can be run with no flags as long as its run within clerk/clerk-docs repo and the current checked out branch is the one you want to migrate. To speed up the migration script significantly you can specify --clerk-path and point it to a local clone of clerk/clerk repo for it to use, otherwise it clones it to a temp repo to perform the migration.

Usage:
  tsx ./scripts/migrate-clerk-docs-to-clerk.ts [options]

Run from your clerk-docs feature branch (not main). Migrates that branch into clerk under clerk-docs/.

By default clones the clerk repo (see --clerk-repo) into a temp directory (needs gh auth with push access). Use --clerk-path for an existing local clone instead.

Optional:
  --clerk-path <path>         Path to the local clerk (default: clones into a temp directory)
  --clerk-repo <owner/repo>   Target PR repo (default: clerk/clerk)
  --clerk-base <branch>       Branch in clerk to base the new PR on (default: main)
  --allow-dirty-clerk         Skip preflight error when local clerk has uncommitted changes

  --docs-path <path>          Path to the clerk-docs repo (default: cwd)
  --docs-repo <owner/repo>    Source PR lookup (default: clerk/clerk-docs)
  --docs-base <branch>        Desired checked-out branch in clerk-docs before migration starts
  --allow-dirty-docs          Skip preflight error when clerk-docs has local uncommitted changes

  --local-only                Create branch locally only (skip push, PR creation, and source-PR comment)
  --dry-run                   Print actions only
  --pr <number>               Open clerk-docs PR to use when several match this branch (required if stdin is not a TTY)
  --debug, --verbose          Verbose logs (includes JSON metadata)
  --help

This script

1. Runs a bunch of pre-checks to ensure the users environment has what we need, this includes git, git-filter-repo, and gh.
2. Clones clerk/clerk if a path to one isn't supplied, creating a new branch for this branch
3. Uses git-filter-repo to merge clerk-docs in to clerk/clerk, pulling over the authoring history
4. Removes clerk-docs from the gitignore
5. Recreates the PR currently open for the branch if it exists in clerk/clerk

That last step of recreating the pr is why this script needs to be run locally, so then the pr has the correct author.

This pr also brings in a github workflow to ask the owner of the pr to run the script to perform the migration.

Note that this migration script does not migrate the github workflows in this pr, those will need to be manually moved and changed to work as desired. This includes getting typedocs pulled in to the clerk/clerk repo instead and the api errors updates.

Additionally we will need to block merging to main in this repo once this pr gets merged. We should also decide if we want to private + archive this repo. Or leave it public and have the clerk-docs folder sync back from clerk/clerk repo back to this repo for the public to view.

this pr also doesn't currently update the readme.md or contributing.md to reflect the changed setup. it could be updated to be.

An example branch created by this script https://github.com/clerk/clerk/tree/nick/my-example-change-migrated-migrated-1 based off this branch https://github.com/clerk/clerk-docs/tree/nick/my-example-change

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
clerk-docs	Ready	Preview	May 13, 2026 2:54pm

[NWylynko]

Opened the pr for the wrong branch, whoops