QGIS Plugin CI

Contains scripts to perform automated testing and deployment for QGIS plugins. These scripts are written for and tested on GitHub, Travis-CI, github workflows and Transifex.

• Deploy plugin releases on QGIS official plugin repository
• Publish plugin in Github releases, option to deploy a custom repository
• Easily integrated in Travis-CI or github workflows
• Completely handle translations with Transifex:

- create the project and the languages - pull and push translations - all TS/QM files can be managed on the CI, the i18n folder can be omitted from the Git repository

• changelog section in the metadata.txt can be populated if the CHANGELOG.md is present
• set the experimental flag according to the tag if needed

📖 For further information, see the documentation.

QGIS-Plugin-CI is best served if you use these two conventions :

• Semantic versioning
• Keep A Changelog

Command line

usage: qgis-plugin-ci [-h] [-v] [--version] [--no-validation] {package,changelog,release,pull-translation,push-translation} ...
Package and release QGIS plugins from the command line.
options:   -h, --help            show this help message and exit   -v, --verbose         Verbosity level: None = WARNING, -v = INFO, -vv = DEBUG (default: 1)   --version             show program's version number and exit   --no-validation       Turn off validation of the version to be released or packaged (default: False)
commands:   qgis-plugin-ci command
{package,changelog,release,pull-translation,push-translation}     package             creates an archive of the plugin     changelog           gets the changelog content     release             release the plugin     pull-translation    pull translations from Transifex     push-translation    update strings and push translations

📜 See the full CLI reference in documentation.

Requirements

• The code is under a git repository (git archive is used to bundle the plugin).
• There is no uncommitted changes when doing a package/release (althought there is an option to bypass this requirement).
• A configuration at the top directory either in .qgis-plugin-ci or in setup.cfg or pyproject.toml with a [qgis-plugin-ci] section (see docs/configuration/options.md for details).
• The source files of the plugin are within a sub-directory with a metadata.txt file with the following fields:

- description - qgisMinimumVersion - repository - tracker

See parameters.py for more parameters and details. Notice that the name of this directory will be used for the zip file.

QRC and UI files

• Any .qrc file in the source top directory (pluginpath) will be compiled and output as filenamerc.py. You can then import it using import pluginpath.resourcesrc
• Currently, qgis-plugin-ci does not compile any .ui file.

Publishing plugins

When releasing, you can publish the plugin :

• In the official QGIS plugin repository. You need to provide user name and password for your Osgeo account.
• As a custom repository in Github releases and which can be added later in QGIS. The address will be: ORG/REPO/releases/latest/download/plugins.xml>

Both can be achieved in the same process.

Pre-release and experimental

In the case of a pre-release (either from the tag name according to Semantic Versioning or from the GitHub release), the plugin will be flagged as experimental.

The tool will recognise any label use as a suffix to flag it as pre-release :

• 10.1.0-beta1
• 3.4.0-rc.2

Debug

In any Python module, you can have a global variable as DEBUG = True, which will be changed to False when packaging the plugin.

Other tools

QGIS-Plugin-Repo

QGIS-Plugin-CI can generate the plugins.xml file, per plugin. If you want to merge many XML files into one to have a single QGIS plugin repository providing many plugins, you should check QGIS-Plugin-Repo. It's designed to run on CI after QGIS-Plugin-CI.