Add script to facilitate the migration of prs to clerk/clerk, add github action to tell people to migrate

[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/.

Re-running on the same clerk-docs branch is safe: the script detects the existing `${headRef}-docs-migration` branch in clerk and updates it with new commits instead of creating a duplicate branch or PR (a clerk PR is opened on re-run only if the branch has none yet). Update mode follows the existing clerk PR's base branch. If the existing clerk PR is CLOSED or MERGED the script aborts with instructions; if the re-merge conflicts, resolve in your IDE and push manually (or abort and re-run).

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. Use --clerk-path when a conflict is likely, since conflict resolution happens in the clerk workspace.

Unknown flags, duplicate flags, and flags with missing values are rejected. Both "--flag value" and "--flag=value" forms work.

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); must match the clerk clone's origin remote
  --clerk-base <branch>       Branch in clerk to base the new PR on (default: main). In update mode the existing clerk PR's base wins; passing a conflicting --clerk-base aborts.
  --target-branch <branch>    Clerk-side branch name to migrate into, e.g. nick/my-new-branch (default: <docs-branch>-docs-migration). If that branch already exists on clerk, the run updates it instead of creating a new branch.
  --allow-dirty-clerk         Skip clean-tree preflight for local clerk (only applies with --clerk-path); uncommitted changes stay in your working tree and are not included in the PR

  --docs-path <path>          Path to the clerk-docs repo (default: cwd)
  --docs-repo <owner/repo>    Source PR lookup (default: clerk/clerk-docs); must match the clerk-docs checkout's origin remote
  --docs-base <branch>        Desired checked-out branch in clerk-docs before migration starts
  --allow-dirty-docs          Skip clean-tree preflight for clerk-docs; only committed history is migrated (filter-repo reads commits, not the working tree), though the merge of origin/main can still abort if local edits conflict
  --allow-docs-main           Skip the preflight refusal when the current clerk-docs branch is "main". Off by default because migrating main rewrites the entire clerk-docs history into clerk; only use it when you know that is what you want (e.g. a one-shot full-history import).

  --local-only                Create or update the migrated branch in the clerk workspace only (skip push, PR creation, and source-PR comment). Requires --clerk-path;without it the branch would only exist in a temp clone that is deleted at the end of the run.
  --dry-run                   Print planned actions without git/GitHub writes (still performs read-only gh calls for auth, permissions, and PR lookups)
  --pr <number>               Open clerk-docs PR to use for this branch; always validated against the open PRs for the branch. Required when several PRs match and stdin is not a TTY.
  --no-close-source-pr        Skip closing the source clerk-docs PR after the backlink comment is posted (default: close it; the close is skipped automatically if thecomment fails)
  --no-merge-main             Skip merging origin/main into the current clerk-docs branch before migration (default: merge it). Use when the branch is already up to date or you want to migrate it as-is.
  --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	Jul 3, 2026 6:25pm

[NWylynko]

Opened the pr for the wrong branch, whoops