Release¶

This command is specific for plugins hosted on GitHub.

Command help¶

usage: qgis-plugin-ci release [-h] [--release-tag RELEASE_TAG]
                              [--transifex-token TRANSIFEX_TOKEN]
                              [--github-token GITHUB_TOKEN] [-r]
                              [--no-repository-stylesheet] [-c] [-d]
                              [-a ASSET_PATH]
                              [--alternative-repo-url ALTERNATIVE_REPO_URL]
                              [--qgis-token QGIS_TOKEN]
                              [--osgeo-username OSGEO_USERNAME]
                              [--osgeo-password OSGEO_PASSWORD]
                              release_version

Positional Arguments¶

release_version: The version to be released (x.y.z).

Named Arguments¶

--release-tag

The release tag, if different from the version (e.g. vx.y.z).

--transifex-token

The Transifex API token. If specified translations will be pulled and compiled.

--github-token

The Github API token. If specified, the archive will be pushed to an already existing release.

-r, --create-plugin-repo

Will create a XML repo as a Github release asset. Github token is required.

Default: False

--no-repository-stylesheet

Do not embed the XSL stylesheet reference in the generated plugins.xml.

Default: False

-c, --allow-uncommitted-changes

If omitted, uncommitted changes are not allowed before releasing. If specified and some changes are detected, a hard reset on a stash create will be used to revert changes made by qgis-plugin-ci.

Default: False

-d, --disable-submodule-update

If omitted, a git submodule is updated. If specified, git submodules will not be updated/initialized before packaging.

Default: False

-a, --asset-path

An additional asset path to add. Can be specified multiple times.

--alternative-repo-url

The URL of the endpoint to publish the plugin (defaults to plugins.qgis.org)

--qgis-token

The token from https://plugins.qgis.org to publish the plugin. Incompatible with the OSGeo user name.

--osgeo-username

The OSGeo user name to publish the plugin. Incompatible with QGIS token.

--osgeo-password

The OSGeo password to publish the plugin. Incompatible with QGIS token.

If the exit code is 2, it means the upload to the QGIS plugin server has failed.

Additional metadata¶

When packaging the plugin, some extra metadata information can be added if these keys are present in the metadata.txt:

commitNumber= : the commit number in the branch otherwise 1 on a tag
commitSha1= : the commit ID
dateTime= : the date time in UTC format when the packaging is done

Tip

These extra parameters are specific to QGIS Plugin CI, so it’s strongly recommended storing them below a dedicated section:

[tool:qgis-plugin-ci]
commitNumber=
commitSha1=
dateTime=

Custom repository¶

qgis-plugin-ci package -c -u https://oslandia.gitlab.io/qgis/oslandia/ latest

Generates the following plugins.xml file:

<?xml version = '1.0' encoding = 'UTF-8'?>
<?xml-stylesheet type="text/xsl" href="plugins.xsl"?>
<plugins>
    <pyqgis_plugin name="Oslandia" version="0.20.0">
        <about><![CDATA[The Oslandia plugin that gives access to our news, ideas, fun features and exclusive support services for our end-customers right into QGIS.]]></about>
        <author_name><![CDATA[Oslandia]]></author_name>
        <create_date>2026-05-15T00:00:00+00:00</create_date>
        <deprecated>False</deprecated>
        <description><![CDATA[Official plugin for Oslandia customers]]></description>
        <download_url>https://oslandia.gitlab.io/qgis/oslandia/oslandia.0.20.0.zip</download_url>
        <experimental>True</experimental>
        <file_name>oslandia.0.20.0.zip</file_name>
        <homepage><![CDATA[https://oslandia.gitlab.io/qgis/oslandia/]]></homepage>
        <icon>resources/images/default_icon.png</icon>
        <repository><![CDATA[https://gitlab.com/Oslandia/qgis/oslandia/]]></repository>
        <qgis_maximum_version>4.10.16</qgis_maximum_version>
        <qgis_minimum_version>3.34.6</qgis_minimum_version>
        <server>False</server>
        <tags><![CDATA[Oslandia,support,maintenance,client,support,GitLab]]></tags>
        <tracker><![CDATA[https://gitlab.com/Oslandia/qgis/oslandia/-/issues]]></tracker>
        <update_date>2026-05-15T00:00:00+00:00</update_date>
        <uploaded_by><![CDATA[Oslandia]]></uploaded_by>
        <version>0.20.0</version>
    </pyqgis_plugin>
</plugins>

Since its version 2.10, it comes by default with a plugins.xsl stylesheet to make the plugins.xml human-readable. If you prefer having a raw plugins.xml, use the --no-repository-stylesheet option.

QGIS Plugin CI - Custom plugins repository with stylesheet