automattic / wpcom-migration
Development tooling for the Migrate to WordPress.com plugin repository.
Package info
github.com/Automattic/wpcom-migration
Type:project
pkg:composer/automattic/wpcom-migration
Requires
None
Requires (Dev)
Suggests
None
Provides
None
Conflicts
None
Replaces
None
- dev-trunk
- 6.78
- 6.77
- 6.76
- 6.75
- 6.74
- 6.73
- 2.0.0
- 1.0.1
- 1.0.0
- 0.1.0
- dev-add/multisite-network-admin
- dev-add/multisite-site-screens
- dev-add/multisite-export
- dev-remove/main-screen-flag
- dev-update/migration-key-fallback-copy
- dev-update-reprint-server-0.11.6
- dev-activation-redirect-interference
- dev-add/from-wpcom-migration-authorize
- dev-add/agents-md
- dev-remove/salted-credential-hashes
- dev-add/redirect-after-connect
- dev-add/continue-url-destination
- dev-add/deploy-wporg
- dev-update/changelog-pr-numbers
- dev-add/main-screen-flag
- dev-fix/restrict-manual-export-to-admins
- dev-add/admin-screens
- dev-add/screen-modes
- dev-add/connection-on-one-screen
- dev-add/app-password-provisioning
- dev-add/wpcom-connection
- dev-add/reprint-server-integration
- dev-migration/branch-2.0.0
- dev-migration/branch-1.0.1
- dev-migration/branch-1.0.0
- dev-migration/branch-0.1.0
This package is auto-updated.
Last update: 2026-11-19 14:59:05 UTC
README
Source for the Migrate to WordPress.com plugin. This repository is the source of record. The tree that ships is built from it.
Layout
plugin/— the plugin. Most of it is the upstream BlogVault tree.plugin/reprint/— the Reprint exporter, its screens, and the REST routes WordPress.com sets it up through.plugin/connection/— the Jetpack connection to WordPress.com and its part of the screen.bin/— the build and the release tooling.tests/e2e/— Playground scenarios that boot the built plugin and drive the exporter, the screens, the routes and the connection.tests/release/— tests for the release tooling.
Build
Needs PHP 8.2+, Composer, rsync, zip.
composer install # PHPCS, WPCS
bin/build.sh
The build writes build/wpcom-migration/ and build/wpcom-migration.zip. The plugin itself runs on PHP 7.4 or newer, the floor of the Jetpack packages it uses. To activate a source checkout without building, run composer install --no-dev --working-dir=plugin first.
How a migration works
WordPress.com copies sites with Reprint. This plugin implements Reprint's server module to spec, which is what WordPress.com exports the site through. It also adds REST API endpoints that set up the credential Reprint signs its requests with: a public key where the host has OpenSSL, a shared HMAC secret elsewhere. WordPress.com calls those endpoints with an application password or a Jetpack user token.
Where application passwords are unavailable, the administrator connects the site to WordPress.com from the Connection screen, or the plugin shares the connection of a site that already runs Jetpack. As a manual fallback, the administrator can paste the migration key WordPress.com shows into the Migration Key screen.
Deactivating the plugin disconnects it and discards the credentials.
The screens
- Connection (
admin.php?page=wpcom-migration-status) — connects the site to WordPress.com, then sends the user on to the migration there. - Migration Key (
admin.php?page=wpcom-migration-key) — where an administrator pastes the migration key. admin.php?page=wpcom-migration-manual— a debugging screen for setting up the credential by hand. Nothing links to it.admin.php?page=wpcom-migration— the BlogVault screen the plugin had before Reprint, kept as a fallback. Nothing links to it on a single site. On multisite it is the only screen, since Reprint can't migrate a network.
Releasing
Run Tag release from the Actions tab with minor, major or a custom version. It commits the new version and its changelog to trunk and tags the commit. Release then builds and tests the tag and publishes a GitHub release, and Deploy to WordPress.org commits that release to the plugin directory. Each step can be retried by dispatching it with the tag.
The changelog is made from the titles of the pull requests merged since the last release. AGENTS.md says how to write them.
Known limitations
- The reprint client appends
&reprint-apito any URL that lacks it. Ifreprint-server-wp, the canonical Reprint WordPress plugin from the Reprint repository, is active and loads first, it answers onreprint-apibefore this plugin runs.
Security
Need to report a security vulnerability? Go to https://automattic.com/security/ or directly to our security bug bounty site https://hackerone.com/automattic.