flatpak-builder-lint

flatpak-builder-lint is a linter for Flatpak artifacts like Flatpak manifests, Flatpak Builder build artifacts and repos. It is primarily developed for Flathub, but can be useful for general use as well.

Checks

There are four checks available right now - the appstream check, the manifest check, the builddir check and the repo check. The manifest and the repo checks are run on Flathub infrastructure.

• The appstream check expects path to a Metainfo file as input. This is a wrapper for appstreamcli validate with some Flathub specific overrides.
• The manifest check expects path to a Flatpak manifest as input.
• The builddir check expects path to a build directory generated by Flatpak Builder as input.
• The repo check expects path to an OSTree repository exported by Flatpak Builder as input.

The last two are created when building the application with the proper arguments to Flatpak Builder.

Some checks may require network connectivity. Sentry integration is used only if SENTRY_DSN environment variable is set.

Exceptions

Errors can be overridden through exceptions.

Exceptions must be submitted to Flathub if the app is meant to be published on Flathub or already exists on Flathub.

Local exceptions

This option should be used sparingly as some errors should never be ignored and it may hide errors that will fail on Flathub.

For ignoring errors locally (for example in CI outside Flathub), the --user-exceptions argument can be used to point it to a local JSON file containing exceptions:

flatpak-builder-lint --exceptions --user-exceptions exceptions.json {manifest,builddir,repo} path

The JSON file must be in the following format:

{
    "com.foo.Bar.Devel": [
        "linter-error-1"
    ],
    "com.foo.Bar.Nightly": [
        "linter-error-2"
    ]
}

If it is passed only local exceptions loaded from the file, matching the app ID will be used, otherwise it will use remote exceptions from Flathub.

Installation

The only supported ways to install and use are Flatpak and Docker.

Flatpak

flatpak-builder-lint is part of the org.flatpak.Builder flatpak package available on Flathub. Set up FlatHub first, then install org.flatpak.Builder:

flatpak install flathub -y org.flatpak.Builder

To run the manifest check:

flatpak run --command=flatpak-builder-lint org.flatpak.Builder manifest com.foo.bar.json

To run the repo check:

flatpak run --command=flatpak-builder-lint org.flatpak.Builder repo repo

The Flatpak package tracks the git commit currently used on the Flathub infrastructure.

Docker

The latest build of flatpak-builder-linter can be used with Docker.

docker run --rm -it ghcr.io/flathub/flatpak-builder-lint:latest --help

To run the manifest check:

docker run -v $(pwd):/mnt --rm -it ghcr.io/flathub/flatpak-builder-lint:latest manifest /mnt/com.foo.bar.json

To run the repo check:

docker run -v $(pwd):/mnt --rm -it ghcr.io/flathub/flatpak-builder-lint:latest repo /mnt/repo

You may need to pass :Z if your distro is using SELinux like so -v $(pwd):/mnt:Z.

Local environment

Installing flatpak-builder-lint locally with uv or pip is not recommended unless for development purposes. It depends on patches that are found in the org.flatpak.Builder flatpak package and on external tools.

Contributing

Dependencies

The following system dependencies must be installed:

• libgirepository1.0-dev, gir1.2-ostree-1.0, gir1.2-appstream-1.0
• flatpak-builder for validating flatpak-builder manifests
• appstreamcli from org.flatpak.Builder for validating MetaInfo files

#!/bin/sh

exec flatpak run --branch=stable --command=appstreamcli org.flatpak.Builder ${@}

• desktop-file-validate to validate desktop files
• git to check if a directory is a git repository

Debiab/Ubuntu:

sudo apt install git appstream flatpak-builder libgirepository1.0-dev gir1.2-ostree-1.0 gir1.2-appstream-1.0 libcairo2-dev desktop-file-utils

ArchLinux:

sudo pacman -S --needed git appstream flatpak-builder desktop-file-utils ostree glib2

Fedora:

sudo dnf install git appstream flatpak-builder desktop-file-utils ostree-libs glib2-devel cairo-devel

Clone the repo:

git clone https://github.com/flathub/flatpak-builder-lint.git && cd flatpak-builder-lint

Then the project can be run with:

uv run --all-groups --frozen -q flatpak-builder-lint --help

Dependencies can be added to removed with uv add and uv remove while uv lock will regenerate the lockfile. uv lock -P can be used to upgrade a specific package or uv lock -U to upgrade everything.

The following Python dependencies are installed and needed to run the project: jsonschema, requests, requests-cache, lxml, sentry-sdk and PyGObject. Additionally setuptools is necessary to build the project. dunamai is used to generate a version from the git commit, since no tags or releases are done, in absence of which it will default to the version of the last tag made.

Formatting and Linting

Ruff is used to lint and format code. MyPy is used to check Python types.

A set of pre-commit hooks are provided to automate the formatting and linting:

uv run --frozen -q pre-commit install

To uninstall:

uv run --frozen -q pre-commit uninstall

Or run individually:

uv run --frozen -q ruff format

uv run --frozen -q ruff check --fix --exit-non-zero-on-fix

uv run --frozen -q mypy .

Tests

Pytest is used to run tests.

uv run --frozen -q pytest -vvv

An additional Flat manager test can be run when modifying code relying on the flatmanager check. The test is meant to be run on CI and not locally. If it is being run locally, it must be run from the root of the git repository using

./tests/flatmanager.sh

To avoid cleanup run as:

NO_CLEAN_UP=1 ./tests/flatmanager.sh

To write tests for manifest checks, recreate a minimal Flatpak builder manifest with the cases to check against and put it in tests/manifests. Then add the test using it (or modify the existing tests) in tests/test_manifest.py.

Similarly to add a test for builddir check, recreate the metadata, cataloge, metainfo, desktop files as needed and put them in a subdirectory of tests/builddir. Then add the test in tests/test_builddir.py. There are helper functions in tests/test_builddir.py to emulate a flatpak-builder build directory using the source files.

Please avoid adding binary files that aren't readable.

Development environment

A development environment is also available as a docker container. To use it to run tests or for linting execute the below from the root of the repository:

./docker/build.sh

This gives an active shell inside the container with all the necessary tools available and any changes made are available once the container is exited. The same environment can also be used from the docker images published to GitHub if rebuilding the latest isn't necessary:

docker run -it --rm --entrypoint= -v $(pwd):/mnt:Z -w /mnt ghcr.io/flathub-infra/flatpak-builder-lint:latest bash

Usage

usage: flatpak-builder-lint [-h] [--version] [--exceptions] [--user-exceptions USER_EXCEPTIONS] [--appid APPID] [--cwd] [--ref REF]
                            {appstream,manifest,builddir,repo} path

A linter for Flatpak builds and flatpak-builder manifests

positional arguments:
  {appstream,manifest,builddir,repo}
                        Type of artifact to lint

                        appstream expects a MetaInfo file
                        manifest expects a flatpak-builder manifest
                        builddir expects a flatpak-builder build directory
                        repo expects an OSTree repo exported by flatpak-builder
  path                  Path to the artifact

options:
  -h, --help            Show this help message and exit
  --version             Show the version number and exit
  --exceptions
                        Skip warnings or errors added to exceptions.
                        Exceptions must be submitted to Flathub
  --user-exceptions USER_EXCEPTIONS
                        Path to a JSON file with exceptions
  --appid APPID         Override the app ID
  --cwd                 Override the path parameter with current working directory
  --ref REF             Override the primary ref detection

If you consider the detected issues incorrect, please report it here: https://github.com/flathub/flatpak-builder-lint

Documentation

A list of errors and warnings and their explanations are available in the Flatpak builder lint page.