Creating a Joomla! update server with Github

3 minutes read

Joomla update server requirement

The Joomla! extension directory (JED) requires that new software packages for Joomla have an update server. If you're a developer without a website, but you still want to meet that requirement, you can use Github! Github hosts your git-repository and the raw files in your repository are accessible from the web. In short, you can use Github as your Joomla! update server.

Open any file in any Github repository and you'll notice the Raw button. Clicking on this button opens the file but in a raw format. Github only sends the contents of the file and nothing more, meaning you'll receive the update XML file as-is.

What about the package files?

We now know that XML files can be hosted on Github, but what about the update package files? Don't worry, there's a solution for that too. Github offers a functionality called Releases, which are rich tags. Releases (or tags) can be downloaded as a zip. Your whole repository will then be zipped at the state of the release.

There's a pitfall though. The whole repository is being zipped, so if you have multiple packages you'll either have to manually package multiple extensions and push them or create multiple repositories.

Creating the updates.xml file

Start by creating a updates.xml file, assuming you don't have one yet. Copy the example updates.xml from the example repository to your local file. Replace the data between the tags and make sure the element, client and folder (in case of a plugin) are matching those in the Joomla extensions table.

You can download the example repository as a zipfile and install it into your Joomla website. Then, search for updates!

You'll notice that the v1.1.0 version references the v1.0.0 version in the updates.xml file. This is for demonstration purposes only to show you that you can update the module. However, the update always persists because the local module version will never be 1.1.0. You should avoid that in production! Every time you push a new release, make sure to update the updates.xml file too so others will receive the update in their Joomla website.

Also, make sure you add or update the existing update server of your extension to match it with the raw updates.xml file in your Github repository. Check the mod_updateserver.xml file for an example.

Testing your update server

Making sure the test server is working is a pretty important part of the process. Testing is easy, even without disturbing the update process. The easiest method is to simply edit the local version of your extension in the #__extensions table of Joomla to a lower one. The current version is located in the manifest column. Update the version to a lower one and then check for updates in your Joomla updater. If all is set up correctly, you should see the current version of your extension as an update. Check it, update it and make sure it works.

Creating releases in Github

Keep your versions tidy and structured using the releases-system in Github. Releases can be downloaded as a zip by users, but also by servers. Every time your extension has a new version, publish a release. Make sure your update your updates.xml file accordingly before publishing the release. Joomla will then pick up the new release and download the release archive. Check the example updates.xml file to make sure you've got it right!

Pitfalls

This system is great and all, but it comes with a few pitfalls. For starters, your software has to be open-source (public) for other servers to see your raw updates.xml file. Private repositories are not supported and need a webserver after all. You're also depending on Github, which went down for 8 hours a while ago. That means no updates for your clients!

I hope you learned something useful and start using this technique for yourself! It keeps everything together and promotes the open-source part of your software.

Share on