A collection of tools for migrating to Ghost.
Each tool has its own detailed documentation:
- Ghost
- beehiiv
- beehiiv API
- beehiiv API Members
- beehiiv Members
- Blogger
- Buttondown
- Chorus
- Curated
- Curated members
- Jekyll
- Letterdrop
- Libsyn
- Mailchimp Members
- Medium Content
- Medium Members
- Squarespace
- Stripe
- Substack
- Substack members
- Tiny News
- Tiny News Members
- Wix CSV
- WordPress API
- WordPress XML
Migrate is a set of command line tools, install them globally:
npm install --global @tryghost/migrate
Run migrate --help to see a list of available commands.
Basic usage is migrate [source] source-info:
E.g.
migrate medium --pathToZip /path/to/export.zip
migrate wp-api --url https://mywpsite.com
Each source comes with optional flags to customise the migration:
migrate [source] --help will give more detail
This is a mono repository, managed with Nx and pnpm workspaces.
git clonethis repo &cdinto it as usualpnpm installto install all dependencies
To make sure the TypeScript packages are built (immediately and after file changes), use
pnpm build:watchOr run pnpm build once if you don't need the watching.
To run a local development copy, cd into this directory, and use pnpm dev instead of migrate like so:
pnpm dev [source]pnpm lintruns oxlint and checks formatting with oxfmtpnpm formatreformats all files with oxfmtpnpm testruns lint and tests
Knip is used to find unused dependencies, exports, and files across the monorepo. Run it with:
pnpm knipSome dependencies are intentionally kept despite not being directly imported (e.g. optional peer dependencies like sharp). These are listed in knip.json under ignoreDependencies for the relevant workspace.
Packages are published to npm automatically via GitHub Actions using OIDC trusted publishers — no npm token is needed.
The Release and Publish workflow runs every Monday at 15:00 UTC (15:00 UK winter time / 16:00 UK summer time), and can also be started from the Actions tab. It only runs in TryGhost/migrate on main.
- Check commits since the nearest stable
@tryghost/migrate@x.y.ztag reachable frommain. Prerelease tags and tags on unmerged branches are ignored. If there are no new commits, skip the release unlessforceis enabled. - Choose a patch bump when every commit author contains
renovate(case-insensitive), or a minor bump when there are any other authors. A forced release with no new commits defaults to patch. This matches ghst's author-based policy; it does not inspect Conventional Commit prefixes or infer breaking changes. - Run
nx release versionwith that bump for all packages. Packages keep their independent version numbers, and Nx updates workspace dependencies and the lockfile as needed. The pre-version command innx.jsonruns the build, lint, formatting checks, release-planning tests, and package tests before changing any versions. - Create the
Published new versions [skip ci]commit and package tags, check npm OIDC authentication, and push the commit and tags together. Ifmainhas moved or branch rules reject the push, publishing stops. - Pack with pnpm to resolve
workspace:*and catalog references, then publish the packages to npm with provenance and thelatestdist-tag. Versions already on npm are skipped.
The publishing step runs in the same workflow because pushes made with GITHUB_TOKEN do not trigger the usual Test → Publish chain. The release commit also includes [skip ci] to avoid a duplicate chain when a separate release token is used. Release/publish jobs are serialized and an in-progress release is not cancelled by a newer run. Up to 100 pending jobs are retained, so a later authentication check or dry-run does not replace a queued publication.
The workflow file remains publish.yml so existing npm trusted-publisher registrations keep working.
The repository's Ghost default branch ruleset requires a pull request and the Required checks pass status. Automated releases need an identity that can push the already-validated version commit directly:
- Use an automation identity allowed to always bypass that ruleset (a pull-request-only bypass is insufficient).
- Add a repository Actions secret named
RELEASE_TOKENcontaining a token for that identity with Contents: read and write access to this repository. Do not put the token in the workflow file. The workflow suppliesRELEASE_TOKENonly to the release push step through an environment variable. Checkout does not persist credentials, and the push reads its authentication header from the environment without saving it in Git configuration or including it in command-line arguments. This reduces credential exposure during installation, builds, and tests; steps still share the same runner and are not security-isolated. npm publishing continues using OIDC. - If the default GitHub Actions identity already has the necessary bypass, omit
RELEASE_TOKEN; the workflow falls back toGITHUB_TOKENwithcontents: write. That permission alone does not bypass branch rules.
No branch rules or secrets are changed by this code. A release whose push is rejected stops before publishing anything to npm.
Choose a mode when using Run workflow on main:
| Mode | Behaviour |
|---|---|
release (default) |
Run the automatic release process now. Use bump to choose auto, patch, or minor; use force to release even without new commits. Always publishes to latest. |
oidc-check |
Build and verify npm trusted publishing without versioning or publishing. |
dry-run |
Build and preview publishing the existing package versions, without bumping, committing, tagging, pushing, or publishing. Also checks OIDC. |
publish |
Build, validate, and publish existing package versions without another version bump. Use this to finish a partially failed release. |
npm_tag applies to publish and dry-run modes. bump and force only apply to release mode. The dry-run previews existing versions, not a future automatic version bump.
The release commit is pushed before npm publication. If npm fails partway through, run publish to retry the recorded versions; it skips packages that succeeded. Do not force a new release just to retry publishing.
pnpm ship still works for interactive releases, including major bumps and custom versions:
- Run
pnpm shiplocally to version, tag, and push. Nx prompts per package and updates dependent packages. - The push to
mainruns the Test workflow. When it succeeds on thePublished new versionscommit, the publish workflow checks out that exact tested commit. Immediately before publishing, it verifies that the tested commit is still the current remotemainHEAD. Ifmainhas advanced, it skips publishing and records the reason in the run summary, preventing a delayed older release from moving npm'slatesttag backwards. This also skips runs when only an unrelated commit has landed since the release; use manualpublishmode onmainif publication is still needed.
To version one package instead of the whole monorepo, pass --projects:
pnpm ship --projects=@tryghost/mg-contextYou are prompted for the bump level — major, minor, patch, or a custom exact version — for that package alone. Anything depending on it is then bumped a patch automatically, so the published dependents point at the new version rather than the old one. Releasing mg-context, for example, also releases mg-ghost-api, mg-queue and migrate.
The prompt starts on major, so arrow down to the bump you want rather than pressing enter.
Preview the whole thing first with --dry-run, which writes and pushes nothing:
pnpm ship --projects=@tryghost/mg-context --dry-runThe publish workflow skips any version already on npm, so only the packages bumped here are published.
When publishing a package for the first time:
- Create the package in
packages/(see CLAUDE.md for the template) - Set
"version": "0.0.0"in itspackage.json - Commit and merge to
main - From the repo root, version, tag, and push just the new package:
pnpm ship:first-release --projects=@tryghost/mg-<name>
- Manually publish the package to npm (CI can only update packages that already exist on npm):
cd packages/mg-<name> pnpm build && npm publish --access public # If the package has a prerelease tag, add --tag pre pnpm build && npm publish --access public --tag pre
- Register the package as a trusted publisher so CI can handle future releases:
npm trust github <package-name> --repo TryGhost/migrate --file publish.yml --allow-publish --yes # Example: npm trust github @tryghost/mg-example-package --repo TryGhost/migrate --file publish.yml --allow-publish --yes
Copyright (c) 2013-2026 Ghost Foundation - Released under the MIT license.