
The definitive modern guide to maintaining open-source WordPress plugins on GitHub. Automated SVN deployment actions, semantic versioning, and Composer packaging.
A professional open-source WordPress plugin lifecycle separates development source code from published distribution artifacts through an automated pipeline:
Automated test suites verify plugin bootstrapping, service container registration, and REST route permissions.
<?php
declare(strict_types=1);
namespace WPStack\Plugin\Tests;
use WP_UnitTestCase;
use WP_REST_Request;
use WP_REST_Server;
use WPStack\Plugin\Plugin;
final class PluginBootstrapTest extends WP_UnitTestCase
{
private Plugin $plugin;
public function set_up(): void
{
parent::set_up();
$this->plugin = Plugin::getInstance();
$this->plugin->boot();
}
public function testPluginSingletonInstance(): void
{
$secondInstance = Plugin::getInstance();
$this->assertSame($this->plugin, $secondInstance, 'Plugin must enforce strict singleton pattern.');
}
public function testRestRoutesAreRegistered(): void
{
global $wp_rest_server;
$this->assertNotEmpty($wp_rest_server);
$routes = $wp_rest_server->get_routes();
$this->assertArrayHasKey('/my-awesome-plugin/v1/optimize', $routes, 'Plugin REST route must be registered.');
}
public function testRestEndpointRequiresPermissions(): void
{
$request = new WP_REST_Request('POST', '/my-awesome-plugin/v1/optimize');
$response = rest_do_request($request);
$this->assertSame(401, $response->get_status(), 'Unauthorized requests must return HTTP 401.');
}
}
If a critical bug or fatal error escapes into a production release (e.g., v1.4.2), never delete or overwrite the existing tag, as this breaks client package managers and caching proxies. Follow this emergency protocol:
Stable tag to Previous Known Good Version:# Checkout trunk from SVN
svn co https://plugins.svn.wordpress.org/my-awesome-plugin/trunk svn-trunk
cd svn-trunk
# Update Stable tag in readme.txt back to 1.4.1
sed -i 's/Stable tag: 1.4.2/Stable tag: 1.4.1/' readme.txt
# Commit rollback to SVN trunk
svn ci -m "Rollback stable tag to 1.4.1 due to critical regression" --username your_svn_user
v1.4.3): Fix the root cause in Git, bump the version to v1.4.3 across all files, and push a new Git tag (git tag v1.4.3 && git push origin v1.4.3) to trigger the automated CI/CD pipeline.Before any production tag is pushed to Subversion, our CI pipeline spins up an isolated ephemeral WordPress Docker container, installs the newly generated production zip, activates the plugin, and checks for PHP fatal errors or unhandled deprecation notices via WP-CLI.
# scripts/verify-clean-install.sh
#!/usr/bin/env bash
set -euo pipefail
ZIP_PATH="build/my-awesome-plugin.zip"
echo "๐ณ Spinning up clean WordPress Docker container..."
docker run --name wp-clean-test -d -p 8080:80 \
-e WORDPRESS_DB_HOST=127.0.0.1 \
-e WORDPRESS_DB_USER=root \
-e WORDPRESS_DB_PASSWORD=root \
-e WORDPRESS_DB_NAME=wptest \
wordpress:latest
sleep 10
echo "๐ฆ Installing and activating generated plugin artifact..."
docker cp "${ZIP_PATH}" wp-clean-test:/tmp/plugin.zip
docker exec -u www-data wp-clean-test wp plugin install /tmp/plugin.zip --activate --allow-root
echo "๐ Verifying active plugin status and health..."
STATUS=$(docker exec -u www-data wp-clean-test wp plugin is-active my-awesome-plugin --allow-root && echo "ACTIVE" || echo "INACTIVE")
if [ "$STATUS" != "ACTIVE" ]; then
echo "โ Pre-release verification failed: Plugin could not be activated!"
docker rm -f wp-clean-test
exit 1
fi
echo "โ
Clean Docker installation verification succeeded!"
docker rm -f wp-clean-test
Upon successful SVN deployment and GitHub release publication, a dedicated webhook step notifies the engineering and support teams with formatted release notes, download links, and commit digests.
# Part of deploy-wordpress-org.yml
- name: Send Slack Release Notification
uses: slackapi/slack-github-action@v1.26.0
with:
payload: |
{
"text": "๐ *New Plugin Release Published!*",
"blocks": [
{
"type": "section",
"text": {
"type": "mrkdwn",
"text": "๐ *My Awesome Plugin ${{ steps.vars.outputs.tag }}* is now live on WordPress.org and GitHub Releases!\n\n*Changelog:* https://github.com/wpstack/my-awesome-plugin/releases/tag/${{ steps.vars.outputs.tag }}"
}
}
]
}
env:
SLACK_WEBHOOK_URL: ${{ secrets.SLACK_RELEASE_WEBHOOK }}
10up/action-wordpress-plugin-deploy with svn: E170013: Unable to connect to a repository at URL.SVN_PASSWORD secret in GitHub..wordpress-org/ does not appear on the live WordPress.org directory after deployment./assets/ directory with a TTL of up to 6 hours.svn ls https://plugins.svn.wordpress.org/my-awesome-plugin/assets/. The CDN cache will refresh automatically.ERROR: Version mismatch detected!.v1.4.2) but the developer forgot to update Stable tag: 1.4.2 in readme.txt or * Version: 1.4.2 in the PHP plugin header.git tag -d v1.4.2 && git push --delete origin v1.4.2), update the file headers, commit the change, and re-tag.GitHub Actions enforces automated code quality checks (PHPStan, PHPUnit, WPCS), eliminates human error during version tagging, scopes third-party Composer packages automatically, and prevents development files (like tests or config dotfiles) from accidentally leaking into the public SVN repository.
The `.distignore` file functions like `.gitignore`, but specifically tells build scripts and SVN deployment tools which files to exclude from production releases (such as `.github/`, `tests/`, `node_modules/`, `composer.json`, and development tools).
PHP-Scoper parses all third-party Composer vendor packages and prefixes their namespaces with a unique plugin-specific namespace (e.g., `WPStack\Vendor\GuzzleHttp`). This ensures that even if another plugin on the user’s site loads a different version of Guzzle, PHP treats them as distinct classes without collisions.
Place your banners (`banner-772×250.png`, `banner-1544×500.png`), icons (`icon-128×128.png`, `icon-256×256.png`), and screenshots in a `.wordpress-org/` root directory. The deploy action copies these files directly into the SVN `/assets` directory while excluding them from the plugin zip.
If your WordPress.org account has Two-Factor Authentication enabled, you cannot use your standard password in CI. Instead, generate a dedicated SVN Application Password from your WordPress.org profile security dashboard and store it in GitHub repository secrets as `SVN_PASSWORD`.
Our deployment workflow includes a pre-flight validation script that compares the Git tag with the `Stable tag:` in `readme.txt` and `Version:` in the main PHP header. If there is a mismatch, the workflow aborts before making any SVN commits to prevent broken release records.
Yes. Our GitHub Actions workflow compiles a production-ready ZIP archive (with vendor dependencies installed and scoped), calculates SHA-256 checksums, and attaches them to the tagged GitHub Release for direct manual installation.
Running PHPStan at Level 8 detects type errors, unhandled null values, non-existent method calls, and incorrect docblocks across your entire codebase before runtime, preventing white-screen fatal errors from ever reaching end users.

Aditya Bhimrajka is a technology entrepreneur, product strategist, and software solutions expert with over a decade of experience building scalable web and mobile applications. His expertise spans SaaS, AI, cloud technologies, custom software development, and digital transformation. Passionate about solving real-world business challenges through technology, Aditya shares practical insights on WordPress, plugins, software development, startup growth, product strategy, and emerging technologies. At WPStack, he writes actionable, experience-driven content that helps developers, businesses, and website owners build secure, high-performing, and future-ready WordPress solutions.
Post a Comment