WordPress Development

Delivering Updates for Private and Client Plugins Outside WordPress.org

Delivering Updates for Private and Client Plugins Outside WordPress.org

Plugins hosted on WordPress.org get a lot for free. When you release a new version, every site using the plugin sees an update notice in the dashboard, and site owners can update with one click or automatically. Most people never think about how that works. That’s why private plugin updates need planning from day one.

Custom plugins don’t get any of that. If you build a plugin for a client, sell a premium plugin from your own site or maintain an internal plugin used across many sites, WordPress has no idea where to look for new versions. Unless you build an update mechanism, the only way to deliver a fix is to log into each site and upload a new zip file.

That works for one site. It stops working when you have twenty client sites running your custom plugin and you discover a security issue that needs fixing on all of them today.

How WordPress checks for updates

Understanding the core mechanism makes the options clearer. Every twelve hours or so, WordPress sends a list of installed plugins and their versions to api.wordpress.org. The API responds with information about any plugins that have newer versions available. WordPress stores that response in a site transient called update_plugins and uses it to show update notices.

When you click update, WordPress downloads the zip file from the URL in that response and installs it.

For a private plugin, the WordPress.org API knows nothing, so it never reports an update. To deliver updates, your plugin needs to add its own information to that transient, pointing to a version number and download URL that you control.

Option 1: An update checker library

The most common approach uses a library bundled inside your plugin that checks a source you control and injects update information into WordPress’s update system. The best known is Plugin Update Checker by YahnisElsts, which is free, open source and widely used.

It supports several sources:

  • A JSON file on any web server, containing the latest version number and download URL
  • GitHub releases or tags, public or private with an access token
  • GitLab and Bitbucket, similarly

A typical setup in the main plugin file is only a few lines: include the library, then point it at your metadata URL or repository. When you release a new version, you update the JSON file or create a new release tag, and every site using the plugin sees an update notice within a day.

This is the option I use most for client plugins. It’s simple, reliable and requires almost no infrastructure.

The JSON approach

With a JSON file, you host two things: the metadata file describing the latest version and the zip file of that version. The metadata includes the version number, download URL, the WordPress versions it requires and has been tested with, and optionally a changelog shown in the “View details” popup.

Any static web host works, including object storage. For internal or client plugins, that’s often all you need.

The GitHub approach

Pointing the update checker at a GitHub repository means releases become updates automatically. Create a release with a version tag, attach a built zip if your plugin needs a build step, and sites pick it up.

For private repositories, you need an access token stored in the plugin or site configuration. Be careful with this. A token embedded in a plugin distributed to client sites can be extracted by anyone with access to those sites. Use a token with read-only access to that one repository, never a personal token with broad access.

Option 2: A self-hosted update server

For premium plugins sold to many customers, you usually want more than update delivery. You want licence checks, so only paying customers receive updates, and some way to manage licences, renewals and activations.

Several solutions provide this:

  • Easy Digital Downloads with its Software Licensing extension turns a WordPress site into a store and update server.
  • WooCommerce with licensing extensions does the same for WooCommerce stores.
  • Freemius and similar platforms handle sales, licensing, updates and analytics as a hosted service, in exchange for a revenue share.
  • Custom update servers, built on the WP Update Server library or your own code, for full control.

These systems typically work like this: the plugin includes a small updater class, the site owner enters a licence key, and the plugin includes that key when checking for updates. The server validates the licence before returning update information and a time-limited download link.

Option 3: Composer and private repositories

For developers managing sites with Composer, private plugins can be distributed through a private Composer repository, using tools like Satis or private Packagist. Updates are then applied by changing the version constraint and running composer update as part of a deployment.

This suits agencies with a development and deployment workflow, but it isn’t suitable for clients who update plugins through the dashboard themselves.

Option 4: Managed update tools

If you maintain many client sites, management tools such as MainWP, ManageWP and InfiniteWP can upload and update custom plugins across sites from one dashboard. They don’t replace a proper update mechanism, but they’re practical for agencies that already use them and want centralised control rather than letting clients update themselves.

Security considerations

An update mechanism is a powerful thing. Whoever controls the update source can push code to every site that trusts it. That brings responsibilities.

  • Protect the source. Secure the server hosting your metadata, your GitHub account or your licensing site with strong passwords and two-factor authentication. A compromised update source is a supply chain attack waiting to happen.
  • Use HTTPS everywhere. Update checks and downloads must use HTTPS to prevent tampering in transit.
  • Don’t embed powerful secrets. Any token or key inside a distributed plugin should be considered public.
  • Consider signing. Some advanced setups sign release packages and verify signatures before installing. WordPress core doesn’t do this for plugins yet, but you can add your own checks.
  • Version carefully. Use semantic versioning so sites never mistake an older build for a newer one.

Changelogs and communication

Site owners deserve to know what an update contains, especially if it changes behaviour. Include a changelog in the update metadata, so it appears in the “View details” dialog in the dashboard. Note security fixes clearly, so administrators prioritise them.

For client plugins, a short email to clients about significant updates builds trust and reduces “what changed?” support requests.

Testing releases

Before publishing an update, test it like you’d test any plugin release:

  • Install the new version over the previous one on a test site with real data
  • Check that upgrade routines, such as database changes, run correctly
  • Test with the minimum PHP and WordPress versions you support
  • Check that the update notice appears and the one-click update works from the dashboard

The last point is easy to skip and occasionally fails: a zip file with the wrong folder name, for example, installs as a separate plugin rather than replacing the old one. The folder inside the zip must match the installed plugin’s folder name exactly.

Automatic updates for private plugins

WordPress’s automatic background updates work with private plugins too, as long as the update information is in the transient. Site owners can enable auto-updates for your plugin from the Plugins screen. For security releases on client sites you manage, enabling auto-updates means fixes reach every site within a day without anyone logging in.

Choosing the right approach

  • One-off client plugins: an update checker with a JSON file or private GitHub repository.
  • Internal plugins across your own sites: an update checker, or Composer if you deploy with it.
  • Premium plugins sold publicly: a licensing system, self-hosted or as a service.
  • Agency managing many sites: an update checker combined with a site management tool for oversight.

Whichever you choose, set it up before the plugin goes live. Adding an update mechanism later means manually installing the version that includes it on every site first, which is exactly the job you were trying to avoid.

Keep a release checklist

A short written checklist for each release prevents most problems: bump the version in the plugin header and the update metadata, update the changelog, build the zip, test the update on a staging site and only then publish. Set up private plugin updates before the first client site goes live, and fixes will reach every site without a single manual upload.

Frequently asked questions

Can I host a private plugin on WordPress.org?

No. Plugins on WordPress.org are public and must be GPL compatible. Private plugins need their own update mechanism.

Is it safe to give clients a plugin that updates from my GitHub?

Yes, if you use a release-only workflow, protect your account and avoid embedding broad access tokens. Releases should be deliberate, never automatic from every commit.

What happens if my update server goes offline?

Sites simply stop seeing new updates. The installed plugin keeps working. Make sure your plugin doesn’t break or slow down if the update check fails.

Do premium plugins have to be GPL?

Code that runs within WordPress is generally considered derivative of WordPress and therefore GPL. You can charge for access, support and updates, but customers have GPL rights to the code they receive.