WordPress Plugin GitHub Updater

Reusable GitHub updater helper for WordPress plugins, built on top of yahnis-elsts/plugin-update-checker.

Features

• Automatic plugin updates from GitHub.
• Release-asset filtering using regex.
• Branch selection (default: main).
• Canonical static API (GitHubUpdater::init) plus backward-compatible wrapper (GitHub_Plugin_Updater).
• Error handling with WP_DEBUG logging.

Requirements

• WordPress plugin context (ABSPATH must be defined).
• Composer dependency: yahnis-elsts/plugin-update-checker (v5+).
• A public GitHub repository with releases or branch updates.

Install dependency:

composer require yahnis-elsts/plugin-update-checker

Quick Start (Canonical API)

Copy class-github-plugin-updater.php into your plugin and initialize like this:

if ( ! class_exists( \Soderlind\WordPress\GitHubUpdater::class ) ) {
	require_once __DIR__ . '/class-github-plugin-updater.php';
}

\Soderlind\WordPress\GitHubUpdater::init(
	github_url: 'https://github.com/username/plugin-name',
	plugin_file: __FILE__,
	plugin_slug: 'plugin-name',
	name_regex: '/plugin-name\.zip/',
	branch: 'main',
);

Positional equivalent:

\Soderlind\WordPress\GitHubUpdater::init(
	'https://github.com/username/plugin-name',
	__FILE__,
	'plugin-name',
	'/plugin-name\.zip/',
	'main'
);

Backward Compatibility API

GitHub_Plugin_Updater is still available for existing integrations.

\Soderlind\WordPress\GitHub_Plugin_Updater::create(
	'https://github.com/username/plugin-name',
	__FILE__,
	'plugin-name',
	'main'
);

\Soderlind\WordPress\GitHub_Plugin_Updater::create_with_assets(
	'https://github.com/username/plugin-name',
	__FILE__,
	'plugin-name',
	'/plugin-name\.zip/',
	'main'
);

Configuration

GitHubUpdater::init(...)

Parameter	Required	Default	Description
github_url	Yes	-	Full repository URL (https://github.com/owner/repo)
plugin_file	Yes	-	Absolute path to the main plugin file
plugin_slug	Yes	-	Plugin slug used by WordPress
name_regex	No	''	Regex to match release asset zip filename
branch	No	'main'	Branch to track

Notes:

• When name_regex is empty, release-asset filtering is disabled.
• init registration is deferred to WordPress init to be safe regardless of load timing.

Recommended Integration Pattern

From your main plugin file, mirror the vmfa pattern:

if ( ! class_exists( \Soderlind\WordPress\GitHubUpdater::class ) ) {
	require_once __DIR__ . '/class-github-plugin-updater.php';
}

\Soderlind\WordPress\GitHubUpdater::init(
	github_url: 'https://github.com/owner/repo',
	plugin_file: MY_PLUGIN_FILE,
	plugin_slug: 'my-plugin',
	name_regex: '/my-plugin\.zip/',
	branch: 'main',
);

Workflow Setup

This repository includes two workflow templates:

• on-release-add.zip.yml (release-triggered build + upload)
• manually-build-zip.yml (manual build/upload for a provided tag)

Copy them into your plugin repository at .github/workflows/.

Workflow Checklist

1. Set PLUGIN_ZIP to your plugin zip file (example: my-plugin.zip).
2. Keep composer install --no-dev --optimize-autoloader so the updater dependency is packaged.
3. Keep the verification step that checks vendor/yahnis-elsts/plugin-update-checker exists in the zip.
4. Ensure name_regex in PHP matches your zip filename convention.

Troubleshooting

Updates do not appear

1. Confirm your plugin file, slug, repo URL, and branch are correct.
2. Publish a release with an attached zip that matches name_regex.
3. Trigger a manual update check in WordPress Admin (or wait for scheduled checks).

Dependency is missing in release zip

If plugin-update-checker is not in vendor/, updater setup fails. In WP_DEBUG, you will see:

GitHubUpdater (your-plugin-slug): Missing dependency yahnis-elsts/plugin-update-checker...

GitHub API rate limits

Unauthenticated GitHub requests are rate-limited. Keep failed lookup caching enabled in your updater flow and avoid frequent forced checks in production.

Private repositories

This wrapper is designed for public GitHub releases. For private repositories, instantiate plugin-update-checker directly and configure authentication with that library.

Real-World Reference

WordPress plugins at https://github.com/soderlind

License

GPL-2.0-or-later.