BACKENDS

Release backends

A backend answers one question: given a repo and a channel, what's the newest release and what files does it have? Everything else - picking the right file, verifying it, installing it - is the same regardless of backend.

Set with source.provider in config.yaml or --provider on the CLI.

GitHub

source:
  provider: github
  repo: owner/name
  host: ""   # set only for GitHub Enterprise, e.g. https://github.example.com/api/v3

Works against github.com and GitHub Enterprise Server. Private repos need a personal access token (classic or fine-grained, Contents: read) via source.token_env.

Gitea / Forgejo

source:
  provider: gitea
  repo: owner/name
  host: https://git.example.com   # required, no default

Forgejo is a Gitea fork with the same API shape, so one backend covers both. source.host is required - there's no public default instance to fall back to.

GitLab

source:
  provider: gitlab
  repo: owner/name        # or a numeric project ID
  host: https://gitlab.com  # gitlab.com by default, or your self-managed instance

Differs from the GitHub-shaped backends in three ways: projects can be addressed by URL-encoded path or numeric ID, release files are "asset links" rather than uploaded assets, and the token goes in a PRIVATE-TOKEN header instead of Authorization.

Generic (no git host)

For a self-hosted download server, or anywhere that isn't a supported git platform. Two shapes:

A JSON manifest (recommended - gives full metadata):

source:
  provider: generic
  manifest_url: https://example.com/updates/latest.json

{
  "version": "1.2.3",
  "notes": "What changed in this release",
  "published_at": "2026-08-23T12:00:00Z",
  "prerelease": false,
  "assets": [
    {
      "name": "MyApp-1.2.3-windows-installer.exe",
      "url": "https://example.com/dl/MyApp-1.2.3-windows-installer.exe",
      "size": 48210944,
      "sha256": "..."
    }
  ]
}

A bare download URL, for the simplest case where a publisher just drops a file at a stable location:

source:
  provider: generic
  download_url: https://example.com/dl/MyApp-latest-windows-installer.exe

Channels and tag filtering

Every backend shares the same release-selection logic, regardless of provider:

• source.channel: stable (default) skips prereleases; prerelease includes them; any takes whatever's newest.
• Draft releases are always skipped.
• source.tag_pattern is a regex filter, useful when a repo pushes tags for more than one build type. QSnippet's brand, for example, uses tag_pattern: "-release$" to ignore its -windows / -linux standalone build tags.

Adding a new backend

Every backend is a subclass of ReleaseBackend (qupdatetool/backends/base.py) implementing fetch_releases(). Channel filtering, tag matching, and asset lookup are handled by the base class, so a new git host needs only that one method (plus fetch_text_file() / list_directory() if it should support release notes from a notices folder).

See also

• README - configuration file
• DEV_GUIDE for wiring a backend into your brand file
• SECURITY.md §1 for how a fetched release gets verified before anything is installed