At PIE, managing an array of small plugins across multiple clients and offering them publicly brings its own set of challenges. A paramount concern is keeping these plugins consistently up-to-date. The impracticality of manually uploading ZIP directories to a growing list of sites led us to explore a more efficient way, seamlessly integrating with WordPress’ native plugin update mechanism.
Enter YahnisElsts/plugin-update-checker
Yahnis Elsts’ Plugin Update Checker library, a stalwart for over a decade, has been our go-to solution for many years. It provides a robust framework for developers looking for direct integration with WordPress’ native plugin updates. The process involves three main steps:
- Include the library in your plugin.
- Maintain a JSON file containing the latest version information.
- Host a ZIP directory of your plugin for users to download.
While effective, this manual process begs the question – why handle ZIP creation and JSON updates manually?
GitHub Pages: Hosting the JSON File
The second requirement of YahnisElsts/plugin-update-checker is that we host a JSON file somewhere so that the plugin update checker can refer to it and find out information about the latest version of our plugin to recognise when an update is required.
Instead of manual upkeep, GitHub Pages offers an automated solution. By maintaining an “update.json” file in the repository’s root and enabling Github Pages, the file becomes publicly accessible at https://<your username>.github.io/<your repo slug>/update.json. A simple commit to this file triggers the update checker to recognize a new version.
Using Github Workflows to build an artifact
GitHub Workflows are essentially docker-based task runners and provide an ideal solution for creating a distribution-ready ZIP artifact of our plugin. Leveraging these workflows streamlines the entire update process. The workflow, triggered on a new release, automates several key tasks.
We already use Github workflows to deploy many of our projects into development, staging, and production environments at PIE (our library of workflows is publicly available at https://github.com/pie/.github), and our original flow was to use a Github workflow to build our zip and then transfer it via SSH to a linode we use, manually updating our JSON file to point to the new zip folder. That said, a little Google-fu revealed that if we created a named release of our plugin within Github itself, we could also upload a publicly available ‘artifact’ to that release. With this in mind, what is stopping us from using this to host the zip of our release for the Update Checker to download?
Triggering the Workflow on a New Release: Employing a GitHub Action (tag-release-on-push-action), the workflow runs only when a new release is ready. The subsequent steps utilize the version number for further operations.
check_for_release:
runs-on: ubuntu-latest
outputs:
version: ${{ steps.prerelease.outputs.version }}
release_body: ${{ steps.prerelease.outputs.body }}
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
steps:
- id: prerelease
uses: rymndhng/release-on-push-action@master
name: Check if we are running a new release
with:
tag_prefix: ""
bump_version_scheme: norelease
dry_run: true
use_github_release_notes: trueThis allows us to create a pull request against the main branch, and then this workflow will run only if it is labeled as release:major, release:minor, or release:patch. What is also really useful is that the step makes the next version number (be it major, minor, or patch) available to subsequent steps as an output.
The next step of our workflow only runs if check_for_release finds that it has a release label, and both builds our zip artifact and creates the release. The first few lines of this step are below, and perform some simple stuff like checking out the repo and installing our composer dependencies. If you needed to compile SASS or JS, you could also do that here.
create_release:
needs: check_for_release
runs-on: ubuntu-latest
if: needs.check_for_release.outputs.version
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
steps:
- name: Check out the repo
uses: actions/checkout@v3
- name: Install Composer dependencies
uses: php-actions/composer@v6
with:
dev: no
Updating Version Numbers and Editing JSON: Before creating the ZIP, the workflow ensures version consistency across files. It dynamically adjusts version numbers in files like package.json, update.json, and others.
- name: Get current date
id: get_date
run: echo "::set-output name=date::$(date +'%Y-%m-%d')"
- name: Bump the version numbers
run: |
echo "Creating release version ${{ needs.check_for_release.outputs.version }}"
sed -i "s/version\":\ \"[0-9]\+\.\?[0-9]*\.\?[0-9]*/version\":\ \"${{ needs.check_for_release.outputs.version }}/g" ./package.json
sed -i "s/version\":\ \"[0-9]\+\.\?[0-9]*\.\?[0-9]*/version\":\ \"${{ needs.check_for_release.outputs.version }}/g" ./update.json
sed -i "s/download\/[0-9]\+\.\?[0-9]*\.\?[0-9]*/download\/${{ needs.check_for_release.outputs.version }}/g" ./update.json
sed -i "s/Version:\ [0-9]\+\.\?[0-9]*\.\?[0-9]*/Version:\ ${{ needs.check_for_release.outputs.version }}/g" ./${{ github.event.repository.name }}.php
sed -i "s/\[Unreleased\]/\[Unreleased\]\r\n\r\n## \[${{ needs.check_for_release.outputs.version }}\] ${{steps.get_date.outputs.date}} /g" ./changelog.md
git config user.name "Github Actions"
git config user.email "<>"
git add .
git commit -am "Version Numbering"
git push
Build an installable ZIP
In the next step, we go about creating our zip artifact. Within our repo we choose to maintain a ‘.zipignore’ file, much like a ‘.gitignore’ this file lists everything in the repo that we do not want added to our distribution artifact – JSON files, .git related files, SASS, and so on. For convention, we name the zip folder with the same slug as the repository itself.
- name: Check for ignore file
id: check_files
uses: andstor/file-existence-action@v2
with:
files: ".zipignore"
- name: File exists
if: steps.check_files.outputs.files_exists == 'true'
shell: bash
# Only runs if all of the files exists
run: |
sed -i '/^[[:space:]]*$/d' .zipignore
sed 's/^/${{ github.event.repository.name }}\//' .zipignore > ../.zipignore
- name: File does not exist
if: steps.check_files.outputs.files_exists != 'true'
shell: bash
# Only runs if any of the files does not exist
run: |
touch ../.zipignore
# This step creates a zip of the plugin which can be used for installation, and by the plugin updater.
- name: Build required zip artifact
run: |
cd ../
zip -r -q ~/${{ github.event.repository.name }}.zip ./${{ github.event.repository.name }} -x@.zipignore
ls -la ~/
Finally, we create our release, adding the zip directory as an artifact
- name: Create a GitHub release
uses: ncipollo/release-action@v1
with:
tag: ${{ needs.check_for_release.outputs.version }}
name: ${{ needs.check_for_release.outputs.version }}
body: ${{ needs.check_for_release.outputs.release_body }}
token: ${{ secrets.GITHUB_TOKEN }}
artifacts: "~/${{ github.event.repository.name }}.zip" The end result is a new release added to the repo, with a correct version number, and a built artifact ready for downloading by a user, or to be pointed to by the Plugin Updater
This workflow has helped us with distributing plugins tremendously, and not having to host JSON and ZIP files elsewhere, being able to run everything out of a Github repository has saved us unimaginable time and effort.
You can find this workflow, along with other starter functionality in our WordPress Plugin Template over on Github: https://github.com/pie/plugin_template and you can see an example of it in use in many of our publicly available plugins at https://github.com/pie?q=&type=public&language=&sort=