Deploy to WordPress.org
Sync a plugin to the WordPress.org SVN repository, create the version tag and update the readme and assets in one commit.
deploy svn syncs a plugin to its WordPress.org SVN repository. Run it with --dry-run first: it checks out the repository, plans the changes and lists them, without committing. The example uses a local test repository; leave out --svn-url and --slug to use https://plugins.svn.wordpress.org/{slug}/.
npx @wpelevator/wp-release deploy svn --svn-url file:///home/me/svnrepo --slug my-plugin --trunk --svn-tag 1.5.0 --dry-run
== Planned changes
Check out file:///home/me/svnrepo with trunk, tags
Stop if tags/1.5.0 already exists
Sync /home/me/my-plugin (rules from /home/me/my-plugin/.distignore) to trunk/
Copy trunk/ to tags/1.5.0
Skip the commit "Release version 1.5.0" (dry run)
Deploying version 1.5.0.
== SVN status
added tags/1.5.0
added tags/1.5.0/.distignore
added tags/1.5.0/CHANGELOG.md
added tags/1.5.0/includes
added tags/1.5.0/includes/class-thing.php
added tags/1.5.0/my-plugin.php
added tags/1.5.0/readme.txt
added trunk/.distignore
added trunk/CHANGELOG.md
added trunk/includes
added trunk/includes/class-thing.php
added trunk/my-plugin.php
added trunk/readme.txt
Dry run, skipped committing 13 changes.
Without --dry-run, the same command commits the changes:
== Planned changes
Check out file:///home/me/svnrepo with trunk, tags
Stop if tags/1.5.0 already exists
Sync /home/me/my-plugin (rules from /home/me/my-plugin/.distignore) to trunk/
Copy trunk/ to tags/1.5.0
Commit "Release version 1.5.0"
Deploying version 1.5.0.
== SVN status
added tags/1.5.0
added tags/1.5.0/.distignore
added tags/1.5.0/CHANGELOG.md
added tags/1.5.0/includes
added tags/1.5.0/includes/class-thing.php
added tags/1.5.0/my-plugin.php
added tags/1.5.0/readme.txt
added trunk/.distignore
added trunk/CHANGELOG.md
added trunk/includes
added trunk/includes/class-thing.php
added trunk/my-plugin.php
added trunk/readme.txt
Committed revision 4.
Running it again stops, since a published tag never changes unless you pass --force:
Error: tags/1.5.0 already exists in file:///home/me/svnrepo. Pass --force to replace it.
== Planned changes
Check out file:///home/me/svnrepo with trunk, tags
Stop if tags/1.5.0 already exists
Sync /home/me/my-plugin (rules from /home/me/my-plugin/.distignore) to trunk/
Copy trunk/ to tags/1.5.0
Commit "Release version 1.5.0"
Deploying version 1.5.0.
The wp-release-deploy-svn GitHub Action runs this command.
Choose what to write
deploy svn syncs a plugin to the WordPress.org plugin SVN repository. Each SVN write is a separate flag and nothing is written unless requested. All writes go into one commit.
| Flag | Default | Writes |
|---|---|---|
--trunk |
off | Sync the full source directory to trunk/ |
--readme-only |
off | Sync only the readme to trunk/, for updates between releases such as bumping Tested up to. Can't be combined with --svn-tag. |
--svn-tag <version> |
off | Create tags/<version>. With --trunk, the tag is a copy of the synced trunk/. Without it, the tag is built directly from the source files and trunk/ is left alone, for pre-release tags. A leading v is stripped, so v1.2.0 creates tags/1.2.0. |
--assets-dir <dir> |
not set | Sync this directory with banners, icons and screenshots to the SVN assets/ directory. There's no default directory, so assets are only deployed when this is set, and it must exist. |
--no-assets |
Skip the --assets-dir sync for one run, for example when a config always passes --assets-dir. |
Typical runs
Typical runs:
# Deploy 1.2.0 to trunk and the tag, and update the assets
wp-release deploy svn dist --trunk --svn-tag 1.2.0 --assets-dir .wordpress-org
# Tag a pre-release build without touching trunk
wp-release deploy svn dist --svn-tag 1.2.0-rc.1
# Update only the readme between releases
wp-release deploy svn dist --readme-only
# Update only the assets
wp-release deploy svn --assets-dir .wordpress-org
# Deploy exactly the files of a ZIP built earlier
wp-release deploy svn --from-zip my-plugin.1.2.0.zip --trunk --svn-tag 1.2.0
How a deploy works
How a deploy works:
- The options are validated, including the slug, version and readme name, before they're used in URLs or paths.
- With
--trunkor--svn-tag, the files must be a plugin whoseVersionheader matches the version. When--trunkand--svn-tagare combined, the readmeStable tagmust match too; a tag-only run skips that, since a pre-release tag doesn't change the stable tag.--readme-onlyneeds the readme. Nothing is checked out when a check fails. - The repository is checked out sparsely into a new temporary directory, with only the directories that the flags write to. A missing
assets/(ortrunk/,tags/) directory is created. The deploy stops whentags/<version>exists, unless--forcereplaces it. - The files are synced in Node.js, without
rsync: new and changed files are copied, files that are no longer selected are deleted, andsvn addandsvn deletestage them, including files that svn ignores by default. With--trunk,trunk/is then copied to the tag withsvn copy. Without it, the same selected files are synced intotags/<version>instead, and with--forcean existing tag is updated to match, deleting files that are no longer in the build. - Asset images get
svn:mime-typeset for PNG, JPEG, GIF and SVG, the formats that WordPress.org documents for plugin assets. Other formats keep the type that svn assigns. - When
svn statusis empty, the deploy ends without a commit. A dry run logs the status and stops before the commit. Otherwise the changes are committed, and the temporary directory is always removed.
--from-zip reads the files from a ZIP instead of <source-dir>. The ZIP is checked before it's extracted: entries with absolute paths, .. segments or symbolic links, and entries outside a single {slug}/ root folder, are rejected.
Credentials are only needed for the commit, not for dry runs, no-op runs or file:// repositories. Pass the username with --svn-username or SVN_USERNAME and the password in SVN_PASSWORD. svn always runs non-interactively without caching credentials, and the password is passed on the standard input with --password-from-stdin, never on the command line or in the logs.
Validation
Validation:
--readme-onlycan't be combined with--svn-tag, since a tag is a release snapshot that a readme update never changes.--versiondefaults to--svn-tag, then theVersionheader of the deployed files; when--versionand--svn-tagare both set they must match.- Pre-release versions like
1.0.0-rc.1can be tagged, but syncing one totrunk/warns, since trunk is for the development version. --trunkwithout--svn-tagworks but warns, to remind you that updating trunk alone doesn't create a version tag for stable downloads.- A version mismatch throws a
VersionMismatchError, aValidationErrorwith themismatchesand a problem for each, with its file and line. See Logging.