Click here for instructions on installing the plugin and activating it.
In order to host plugins and themes on Gitlab and allow WordPress to handle the update functionality we need to do several things, all of which are controlled by the UpdatesController class found in ‘plugin->Controllers->Admin->UpdatesController’.
Since WordPress looks to its global plugin svn repo to check for updates, we need to provide our own update information via a update filter called ‘pre_set_site_transient_update_plugins’ or ‘pre_set_site_transient_update_themes’. What this does is it allows us to grab information about the given repo via the Gitlab API and tell WordPress if there’s an update needed. We also provide the url where WordPress can download the updated plugin’s zip file (this zip file is just the latest pipeline artifact that was built on a push to ‘master’).
The following is what the UpdatesController returns to WordPress’s update_transient
$this->repositoryInfo = [
'tag_name' => substr($latestTag->name, 1),
'zip_url' => 'https://gitlab.com/api/v3/projects/q4dev%2Fq4vrplugin/builds/artifacts/master/download?job=deploy&private_token=' . $this->private_token,
'body' => $latestTag->release->description,
'published_at' =>
]
// Looks like
[
'tag_name' => 'v1.0.2',
'zip_url' => 'https://gitlab.com/api/v3/projects/q4dev%2Fq4vrplugin/builds/artifacts/master/download?job=deploy&private_token={your-private-token}',
'body' => 'The information in the body of the new tag that was created on Gitlab',
'published_at' = '2017-01-01'
]
If the filter does not return this information as shown WordPress won’t know where to look for an update and it will fail. Gitlab is relatively stable but it’s also changing and improving so there could be issues when using it’s API. To debug this behavior it’s best to pull up phpmyadmin and delete the ‘pre_set_site_transient_update_plugins’ value in the ‘wp_options’ table, which will cause WordPress to check for updates which will trigger the UpdatesController to kick in to action so that you can debug.
Additional info about the Gitlab API
about artifacts
The way artifacts are built is controlled by the .gitlab-ci.yml file found in the root of the repo. The yaml file is a set of instructions that Gitlab’s runners will follow inside a Docker container to create the files needed. The docker container can be hosted anywhere, including your own machine – but Gitlab also offers shared runners which are probably sufficient for these builds. Doing things this way allows us to specify our dependencies in one place (composer.json for PHP dependencies & package.json for JS/CSS dependencies) and not have to check those files in to source control.
Originally we were telling Gitlab to delete any artifact zip that was older than 7 days, but if a plugin is not updated within those 7 days it will be looking for an zip file that is no longer there. There is currently no timeline for expiration but an expire flag can be added to the yaml file if needed and Gitlab doesn’t specify anything about how long it will host these zip files (or how many it will keep).
about release tags
When creating a new tag for updates on Gitlab – be sure to fill in the ‘Release Notes’ – this tells gitlab that this is a ‘release tag’ and not just a regular tag. There are plans for Gitlab to allow these to be automatically created on a successful merge to master but this hasn’t been done yet.