---
title: How to Package and Publish Open-Source WordPress Plugins on GitHub
description: The definitive modern guide to maintaining open-source WordPress plugins on GitHub. Automated SVN deployment actions, semantic versioning, and Composer packaging.
url: https://wpstack.online/2026/11/21/packaging-publishing-opensource-plugins-github
date_modified: 2026-09-12
author: Aditya Bhimrajka
language: en_US
---

The definitive modern guide to maintaining open-source WordPress plugins on GitHub. Automated SVN deployment actions, semantic versioning, and Composer packaging.

## 1. The Architecture of Modern WordPress Plugin Publishing

A professional open-source WordPress plugin lifecycle separates development source code from published distribution artifacts through an automated pipeline:

## 13. Complete PHPUnit Integration Test Suite

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.');
    }
}

```

## 14. Emergency Release Rollback Runbook for SVN

### Production Runbook: WordPress.org SVN Emergency Rollback

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:

1. **Point `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

```
2. **Publish Hotfix Release (`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.

## 15. Pre-Release Verification in Ephemeral Docker Containers

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

```

## 16. Automated Release Announcements to Slack & Discord

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 }}

```

## 17. Operational Incident Runbook: Troubleshooting Publishing Failures

### Production Runbook: WordPress.org SVN & GitHub CI Incidents

1. **SVN Commit Authentication Failure (403 Forbidden):**

- *Symptom:* GitHub Action fails at `10up/action-wordpress-plugin-deploy` with `svn: E170013: Unable to connect to a repository at URL`.
- *Root Cause:* Two-Factor Authentication (2FA) is enabled on the WordPress.org account, or the SVN password secret in GitHub repository settings is expired.
- *Remedy:* Generate a dedicated SVN Application Password from your WordPress.org profile security settings and update the `SVN_PASSWORD` secret in GitHub.
2. **WordPress.org Asset Cache Delay:**

- *Symptom:* Updated plugin banner or icon in `.wordpress-org/` does not appear on the live WordPress.org directory after deployment.
- *Root Cause:* WordPress.org utilizes an aggressive Edge CDN cache for the `/assets/` directory with a TTL of up to 6 hours.
- *Remedy:* Verify that the files exist in the SVN repo: `svn ls https://plugins.svn.wordpress.org/my-awesome-plugin/assets/`. The CDN cache will refresh automatically.
3. **Version Mismatch Pre-Flight Abort:**

- *Symptom:* Deploy workflow terminates with `ERROR: Version mismatch detected!`.
- *Root Cause:* The Git tag was created (e.g., `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.
- *Remedy:* Delete the erroneous local and remote Git tag (`git tag -d v1.4.2 && git push --delete origin v1.4.2`), update the file headers, commit the change, and re-tag.

## Frequently Asked Questions (FAQ)

### 1. Why should I use GitHub Actions instead of manual SVN commits?

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.

### 2. What is the purpose of `.distignore` in WordPress plugin development?

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).

### 3. How does PHP-Scoper prevent plugin dependency collisions?

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.

### 4. How are banner and icon images synced to WordPress.org?

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.

### 5. How do I handle WordPress.org 2FA when deploying via GitHub Actions?

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`.

### 6. What happens if my Git tag and `readme.txt` version do not match?

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.

### 7. Can I publish downloadable ZIP packages to GitHub Releases automatically?

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.

### 8. How does PHPStan static analysis improve plugin stability?

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.

## Primary references

- [WordPress Developer Resources](https://developer.wordpress.org/)
- [WordPress REST API Handbook](https://developer.wordpress.org/rest-api/)
