Continuous integration & delivery#
This repository is driven by seven GitHub Actions workflows. This page explains what triggers each one and
where its output goes — nothing (a pass/fail gate), a run-scoped workflow artifact, a GitHub Release asset,
the gh-pages site, or the official plugins.qgis.org repository.
The plugin is not published to PyPI —
pyramids-qgisships as a QGIS plugin zip. "Publishing" therefore means attaching that zip (and a custom-repositoryplugins.xml) to a GitHub Release and uploading it to plugins.qgis.org, not pushing a wheel to PyPI. (TheWheel - Build & Testworkflow does build a wheel, but only to test the import surface — that wheel is never released.)
Workflows at a glance#
| Workflow | File | Triggers | Output / uploaded to |
|---|---|---|---|
| CI | lint.yml |
push → main, pull_request |
none — gate only (ruff, byte-compile 3.11/3.12/3.13, gitleaks) |
| Tests | tests.yml |
push → main, pull_request |
none — gate only (pytest against real QGIS, matrix dev + qt5) |
| Wheel - Build & Test | pure-wheel-test.yml |
push → main, pull_request, workflow_dispatch |
run-scoped artifact (the built wheel, passed build → test across ubuntu/macos/windows) |
| pip-audit | pip-audit.yml |
pull_request, schedule (Mon 06:00 UTC), workflow_dispatch | none — gate only (dependency audit in the run log) |
| Deploy MkDocs | github-pages-mkdocs.yml |
push → main, pull_request, release published, workflow_run ← github-release |
PR → run-scoped artifact (site-pr-<n> preview); main/release → the gh-pages site |
| github-release | github-release.yml |
workflow_dispatch (release-branch, increment, draft) |
a GitHub Release + git tag (via cz bump → action-gh-release) |
| publish | publish.yml |
workflow_run ← github-release, workflow_dispatch (branch) |
workflow_run → GitHub Release assets (+ plugins.qgis.org); dispatch → run-scoped artifacts |
The five destinations#
- Gate only — the workflow just passes or fails a commit/PR; it uploads nothing durable.
- Run-scoped workflow artifact — a file attached to that one Actions run (download it from the run page; it
expires). Used for the built wheel and the per-PR docs preview, and by
publish's manual path. - GitHub Release asset — a file permanently attached to a Release (
.../releases/download/<tag>/...). The plugin zip andplugins.xmllive here. gh-pagessite — the rendered documentation, committed to thegh-pagesbranch bymikeand served by GitHub Pages.- plugins.qgis.org — the official QGIS plugin repository (the real "publish"). Inert until the
QGIS_TOKENsecret is set.
How triggers map to workflows#
flowchart TD
PR([Pull request]) --> CI[CI: lint.yml]
PR --> TST[Tests: tests.yml]
PR --> WHL[Wheel: pure-wheel-test.yml]
PR --> AUD[pip-audit.yml]
PR --> DOCpr[Deploy MkDocs: build-strict]
PUSH([Push to main]) --> CI
PUSH --> TST
PUSH --> WHL
PUSH --> DOCmain[Deploy MkDocs: deploy-main]
CRON([Schedule: Mon 06:00 UTC]) --> AUD
MANW([Manual dispatch]) --> WHL
MANW --> AUD
MANP([Manual dispatch + branch]) --> PUBd[publish.yml: artifact path]
REL([Manual dispatch: github-release.yml]) --> RELj[cz bump → tag → GitHub Release]
RELj -. workflow_run .-> PUBr[publish.yml: release path]
RELj -. workflow_run .-> DOCrel[Deploy MkDocs: deploy-release]
DOCpr --> A1[/site-pr-n artifact/]
DOCmain --> GP[(gh-pages site)]
DOCrel --> GP
WHL --> A2[/wheel artifact/]
PUBd --> A3[/zip + plugins.xml artifacts/]
PUBr --> RA[(Release assets: zip + plugins.xml)]
PUBr --> QG[(plugins.qgis.org)]
Everyday CI — pull request and push to main#
Every PR runs four gates — CI, Tests, pip-audit, Wheel — plus a strict docs build. A push to main runs the same
set except pip-audit, which is pull-request- and schedule-only. None of them publish; the docs build only
uploads a preview on PRs.
flowchart LR
subgraph Gates["Gates — pass/fail only"]
L["CI (lint.yml)<br/>ruff · byte-compile 3.11/3.12/3.13 · gitleaks"]
T["Tests (tests.yml)<br/>pytest vs real QGIS · dev + qt5"]
A["pip-audit.yml<br/>(PRs + weekly)"]
end
EV([PR or push to main]) --> L
EV --> T
EV -->|PR only| A
EV --> W["Wheel (pure-wheel-test.yml)"]
EV --> D["Deploy MkDocs: build-strict<br/>(warnings = errors)"]
W -->|build-wheel| WA[/wheel artifact/]
WA -->|download| WT["test-wheel<br/>ubuntu · macos · windows"]
D -->|pull_request only| PRA[/site-pr-n preview artifact/]
D -->|push to main| DM[deploy-main ⟶ gh-pages]
The wheel artifact is internal to the run: build-wheel uploads it and test-wheel downloads it to install and
test on all three OSes. It is not a release.
The release pipeline#
A release is started by hand by dispatching github-release.yml. That job bumps the version with commitizen,
pushes the bump commit and the bare tag (0.1.1, not v0.1.1), and creates the GitHub Release. Because a
Release created with the built-in GITHUB_TOKEN cannot trigger another workflow directly, two workflows listen for
github-release to complete via workflow_run:
flowchart TD
M([Maintainer dispatches github-release.yml<br/>inputs: release-branch, increment, draft]) --> CZ["cz bump:<br/>version + CHANGELOG + bare tag"]
CZ --> PUSH[push commit + tag to the release branch]
PUSH --> GR[(Create GitHub Release)]
GR -. "workflow_run: github-release completed" .-> PUB
GR -. "workflow_run: github-release completed" .-> DR[Deploy MkDocs: deploy-release]
subgraph PUB["publish.yml — release path"]
PC["Checkout the TIP of the release branch<br/>= the commitizen-bumped version"] --> PB["qgis-plugin-ci release --create-plugin-repo"]
PB --> PR[("Release assets:<br/>the plugin zip + plugins.xml")]
PB --> PQ[("plugins.qgis.org<br/>inert without OSGEO secrets")]
end
DR --> GP[("gh-pages: versioned docs via mike")]
Checking out the tip of the release branch (not the triggering commit) is essential: github-release pushes the
version-bump commit after the workflow_run SHA is captured, so only the branch tip carries the bumped
metadata.txt version. The build then checks out that version's tag before packaging, so the Release asset is
exactly the tagged commit even if another commit lands on the branch meanwhile.
Caveat — a draft release gets no plugin assets. The release path only uploads when a published Release exists for the tag (the gate queries
/releases/tags/<tag>, which does not return drafts). Ifgithub-releaseis dispatched withdraft: true,publish.ymlfinds no published Release, emits a::warning::, and the job still goes green with nothing uploaded. Publishing the draft later fires areleaseevent, whichpublish.ymldoes not listen for — so publish the Release (non-draft) as part of cutting it, or re-cut the version.
publish.yml — two paths, chosen by trigger#
publish.yml builds the same plugin zip + plugins.xml either way, but where they go depends on how it was
triggered:
flowchart TD
START([publish.yml])
START --> R{Trigger?}
R -->|workflow_run<br/>after github-release| RR[Checkout release branch TIP]
RR --> RB["qgis-plugin-ci release --create-plugin-repo"]
RB --> RREL[(Upload zip + plugins.xml<br/>to the GitHub Release)]
RB --> RQ[(Upload to plugins.qgis.org<br/>if OSGEO secrets set)]
R -->|workflow_dispatch<br/>input: branch| DD[Checkout the given branch TIP]
DD --> DB["qgis-plugin-ci package --plugin-repo-url"]
DB --> DART[/"Upload zip + plugins.xml<br/>as workflow artifacts<br/>(name: pyramids_qgis-VERSION)"/]
workflow_run→ Release. The real publish.qgis-plugin-ci releaseneeds a published Release to attach to, whichgithub-releasehas just created, and--create-plugin-repoalso generates and uploadsplugins.xml.workflow_dispatch→ artifacts only. A safe, throwaway build of any branch for inspection. It usesqgis-plugin-ci package(which needs no Release) and uploads the results as run-scoped artifacts — it never touches a Release. Build frommainby hand here without risk of attaching the wrong source to a release.
Why the split exists: when both triggers uploaded to the Release and the manual path checked out
maininstead of the tag, a hand-run build once attachedmain's source (including post-tag commits) to an already-cut release. Routingworkflow_dispatchto artifacts removes that hazard entirely.
Documentation (MkDocs) deployment#
github-pages-mkdocs.yml always runs a strict (warnings-as-errors) build as a gate, then publishes only for
main and releases. Pull requests build the site and upload a preview artifact but never publish it.
flowchart TD
EV{Trigger}
EV -->|pull_request| BS[build-strict gate]
BS --> PRA[/site-pr-n preview artifact<br/>reviewers download it/]
EV -->|push to main| DMg[build-strict ⟶ deploy-main]
DMg --> GPm[(gh-pages: latest docs via mike)]
EV -->|release published<br/>OR workflow_run ← github-release| DRg[build-strict ⟶ deploy-release]
DRg --> GPr[(gh-pages: versioned docs via mike)]
mike publishes by committing the rendered site to the gh-pages branch, which GitHub Pages serves (Settings →
Pages → Source = gh-pages). PR previews are deliberately not published — each one would otherwise commit a full
site onto the shared gh-pages branch.
deploy-release'srelease: publishedtrigger fires only for a manually published Release. A Release created bygithub-release.ymlwith the built-inGITHUB_TOKENdoes not emit areleaseevent, so in the automated release flowdeploy-releaseruns via theworkflow_runpath only.
Secrets used#
| Secret | Used by | Effect when unset |
|---|---|---|
GITHUB_TOKEN (built-in) |
all | always present |
ACTIONS_DEPLOY_TOKEN |
Deploy MkDocs (deploy jobs) | docs cannot push to gh-pages |
QGIS_TOKEN |
publish.yml (release path) | plugins.qgis.org upload is skipped; the Release assets still publish |