Geekswipe Updater

WordPress updates plugins and themes from WordPress.org. If you write your own and keep them on GitHub, every update means building a zip, uploading it, and picking Replace current with uploaded. This plugin lets WordPress update them from their GitHub releases instead, with the same Dashboard › Updates screen, the same Update button, and the same auto-update toggle.

It's one PHP file with no settings page, and it runs on Geekswipe. It was written with AI, and AI.md says how and what I've checked.

How does WordPress find the updates?

Since WordPress 5.8 for plugins and 6.1 for themes, a plugin or theme can say where its updates come from in an Update URI header. WordPress then leaves it out of its WordPress.org check, and asks whichever plugin answers for that host. This plugin answers for github.com. It reads the repository from the header, asks GitHub for the latest release, and hands WordPress the version and the zip. Everything after that is WordPress's own update code.

Setting up a plugin or theme

1. Name the repository in the header, in the plugin's main file or the theme's style.css.

   Update URI: https://github.com/you/your-plugin

2. Publish GitHub releases tagged like v1.2.3, each with a zip that unpacks to the folder the plugin or theme is installed in. Name the zip after that folder, such as your-plugin.zip. If a release has only one zip, its name doesn't matter.

3. Bump the version in the header for every release. WordPress offers an update only when the release is newer than what's installed.

The updater trusts repositories owned by Geekswipe and nobody else, because whatever a release's zip holds ends up running on your site. To add your own GitHub account, put this in a small plugin of your own.

add_filter( 'geekswipe_updater_owners', fn( $owners ) => array_merge( $owners, array( 'your-github-name' ) ) );

Releasing by pushing

Each Geekswipe repository has a GitHub Actions workflow, .github/workflows/release.yml, that runs on every push to main. When the version in the header has no release yet, it builds the zip with git archive and publishes the release, with the commit message as its notes. So releasing is bumping the version and pushing. Copy the workflow from this repository and change the three settings at its top, which are the file with the Version header, the installed folder's name, and the name in the release title.

Private repositories

A private repository's releases need a GitHub token. Create a fine-grained personal access token under GitHub's Settings › Developer settings › Personal access tokens. Give it the repositories' owner as its resource owner, access to only those repositories, and one permission, Contents set to Read-only. Then add it to wp-config.php.

define( 'GEEKSWIPE_UPDATER_GITHUB_TOKEN', 'your token' );

The token only ever goes to api.github.com. GitHub hands over the zip through a redirect to its file storage, and the updater follows that redirect without the token. A fine-grained token covers one owner's repositories, so keep your private plugins and themes under one account or organisation.

Public repositories update without a token, through GitHub's public download links. GitHub allows a server 60 API requests an hour without one, which is plenty, since WordPress checks twice a day and the updater keeps each answer for an hour.

When does an update show up?

WordPress checks twice a day on its own. Dashboard › Updates checks when you open it, and its Check again link skips the updater's cache, so a release you've just published shows up straight away.

What if GitHub can't be reached?

Dashboard › Updates, Plugins, and Themes show a notice naming the repository and what went wrong, and PHP's error log gets the same line. The notice goes away once a check works. A private repository answers "no release" when the token can't read it, so check the token first.

A word on trust

Anyone who can publish a release in one of these repositories can put code on your site. That's the same trust you give WordPress.org for its plugins, now given to your GitHub account. Turn on two-factor authentication for every account that can push, and think before turning on auto-updates.

Requirements

• WordPress 6.4 or later
• PHP 8.1 or later

Installation

1. Download geekswipe-updater.zip from the latest release.
2. In WordPress, go to Plugins › Add New Plugin › Upload Plugin and upload the zip.
3. Activate it. From then on it updates itself too.

Limitations

• GitHub only. GitLab, Bitbucket, and self-hosted Git aren't supported.
• Drafts and pre-releases are ignored, because GitHub doesn't count them as the latest release.
• Multisite hasn't been tested.

Building a release zip

git archive --format=zip --prefix=geekswipe-updater/ -o geekswipe-updater.zip HEAD

Licence

GPL-2.0-or-later. See LICENSE.