{"id":49232681,"url":"https://github.com/flathub-infra/flatpak-builder-lint","last_synced_at":"2026-04-24T12:35:15.966Z","repository":{"id":59255899,"uuid":"523492060","full_name":"flathub-infra/flatpak-builder-lint","owner":"flathub-infra","description":"A linter for Flatpak manifests and build artifacts primarily developed for Flathub","archived":false,"fork":false,"pushed_at":"2026-04-23T11:13:11.000Z","size":1820,"stargazers_count":60,"open_issues_count":13,"forks_count":296,"subscribers_count":6,"default_branch":"master","last_synced_at":"2026-04-23T13:19:55.778Z","etag":null,"topics":["flathub","flatpak","linter"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/flathub-infra.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2022-08-10T20:46:26.000Z","updated_at":"2026-04-23T11:13:16.000Z","dependencies_parsed_at":"2023-11-10T14:40:56.741Z","dependency_job_id":"a08d0c31-4f77-4811-ae69-ca58e9e70e0b","html_url":"https://github.com/flathub-infra/flatpak-builder-lint","commit_stats":null,"previous_names":["flathub-infra/flatpak-builder-lint","flathub/flatpak-builder-lint"],"tags_count":41,"template":false,"template_full_name":null,"purl":"pkg:github/flathub-infra/flatpak-builder-lint","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flathub-infra%2Fflatpak-builder-lint","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flathub-infra%2Fflatpak-builder-lint/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flathub-infra%2Fflatpak-builder-lint/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flathub-infra%2Fflatpak-builder-lint/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/flathub-infra","download_url":"https://codeload.github.com/flathub-infra/flatpak-builder-lint/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flathub-infra%2Fflatpak-builder-lint/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32224397,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-24T10:26:35.452Z","status":"ssl_error","status_checked_at":"2026-04-24T10:25:27.643Z","response_time":64,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["flathub","flatpak","linter"],"created_at":"2026-04-24T12:35:13.828Z","updated_at":"2026-04-24T12:35:15.960Z","avatar_url":"https://github.com/flathub-infra.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# flatpak-builder-lint\n\nflatpak-builder-lint is a linter for Flatpak artifacts like Flatpak\nmanifests, Flatpak Builder build artifacts and repos. It is primarily\ndeveloped for Flathub, but can be useful for general use as well.\n\n## Checks\n\nThere are four checks available right now - the `appstream` check, the\n`manifest` check, the `builddir` check and the `repo` check. The manifest\nand the repo checks are run on Flathub infrastructure.\n\n- The `appstream` check expects path to a [Metainfo file](https://docs.flathub.org/docs/for-app-authors/metainfo-guidelines/#path-and-filename)\n  as input. This is a wrapper for `appstreamcli validate` with some\n  Flathub specific overrides.\n- The `manifest` check expects path to a [Flatpak manifest](https://docs.flatpak.org/en/latest/manifests.html)\n  as input.\n- The `builddir` check expects path to a build directory generated by\n  Flatpak Builder as input.\n- The `repo` check expects path to an OSTree repository exported by\n  Flatpak Builder as input.\n\nThe last two are created when [building the application](https://docs.flathub.org/docs/for-app-authors/submission#build-and-install)\nwith the proper arguments to Flatpak Builder.\n\nSome checks may require network connectivity. Sentry integration is used\nonly if `SENTRY_DSN` environment variable is set.\n\n## Exceptions\n\nErrors can be overridden through exceptions.\n\nExceptions must be [submitted to Flathub](https://docs.flathub.org/docs/for-app-authors/linter#exceptions)\nif the app is meant to be published on Flathub or already exists on\nFlathub. These exceptions, once published, can be viewed by doing:\n\n```sh\ncurl -s 'https://raw.githubusercontent.com/flathub-infra/flatpak-builder-lint/HEAD/flatpak_builder_lint/staticfiles/exceptions.json'|jq '.[\"my.app.id\"]'\n```\n\n### Local exceptions\n\nThis option should be used sparingly as some errors should never be\nignored and it may hide errors that will fail on Flathub.\n\nFor ignoring errors locally (for example in CI outside Flathub),\nthe `--user-exceptions` argument can be used to point it to a local\nJSON file containing exceptions:\n\n```sh\nflatpak-builder-lint --exceptions --user-exceptions exceptions.json {manifest,builddir,repo} path\n```\n\nThe JSON file must be in the following format:\n\n```json\n{\n    \"com.foo.Bar.Devel\": [\n        \"linter-error-1\"\n    ],\n    \"com.foo.Bar.Nightly\": [\n        \"linter-error-2\"\n    ]\n}\n```\n\nIf it is passed only local exceptions loaded from the file, matching the\napp ID will be used, otherwise it will use remote exceptions from\nFlathub.\n\n## Installation\n\nThe only supported ways to install and use are Flatpak and Docker.\n\n### Flatpak\n\nflatpak-builder-lint is part of the `org.flatpak.Builder` flatpak package\navailable on Flathub. [Set up Flathub][flatpak_setup] first, then install\n`org.flatpak.Builder`:\n\n```bash\nflatpak install flathub -y org.flatpak.Builder\n```\n\nTo run the manifest check:\n\n```sh\nflatpak run --command=flatpak-builder-lint org.flatpak.Builder manifest com.foo.bar.json\n```\n\nTo run the repo check:\n\n```sh\nflatpak run --command=flatpak-builder-lint org.flatpak.Builder repo repo\n```\n\nThe Flatpak package tracks the git commit currently used on the Flathub\ninfrastructure.\n\n### Docker\n\nThe latest build of flatpak-builder-linter can be used with Docker.\n\n```bash\ndocker run --rm -it ghcr.io/flathub/flatpak-builder-lint:latest --help\n```\n\nTo run the manifest check:\n\n```sh\ndocker run -v $(pwd):/mnt --rm -it ghcr.io/flathub/flatpak-builder-lint:latest manifest /mnt/com.foo.bar.json\n```\n\nTo run the repo check:\n\n```sh\ndocker run -v $(pwd):/mnt --rm -it ghcr.io/flathub/flatpak-builder-lint:latest repo /mnt/repo\n```\n\nYou may need to pass `:Z` if your distro is using SELinux like so\n`-v $(pwd):/mnt:Z`.\n\n### Local environment\n\nInstalling flatpak-builder-lint locally with [uv][uv] or pip is\nnot recommended unless for development purposes. It depends on patches\nthat are found in Flathub's fork of [appstream](https://github.com/flathub-infra/appstream/tree/flathub),\n[flatpak](https://github.com/flathub-infra/flatpak/tree/flathub) and\n[flatpak-builder](https://github.com/flathub-infra/flatpak-builder/tree/flathub).\n\n## Contributing\n\n### Dependencies\n\nThe following system dependencies must be installed:\n\n- `libgirepository1.0-dev, gir1.2-ostree-1.0, gir1.2-appstream-1.0`\n- `flatpak-builder` for validating flatpak-builder manifests\n- `appstreamcli` from `org.flatpak.Builder` for validating MetaInfo files\n```sh\n#!/bin/sh\n\nexec flatpak run --branch=stable --command=appstreamcli org.flatpak.Builder ${@}\n```\n- `desktop-file-validate` to validate desktop files\n- `git` to check if a directory is a git repository\n\nDebiab/Ubuntu:\n\n```sh\nsudo apt install git appstream flatpak-builder libgirepository1.0-dev gir1.2-ostree-1.0 gir1.2-appstream-1.0 libcairo2-dev desktop-file-utils\n```\n\nArchLinux:\n\n```sh\nsudo pacman -S --needed git appstream flatpak-builder desktop-file-utils ostree glib2\n```\n\nFedora:\n\n```sh\nsudo dnf install git appstream flatpak-builder desktop-file-utils ostree-libs glib2-devel cairo-devel\n```\n\nClone the repo:\n\n```bash\ngit clone https://github.com/flathub/flatpak-builder-lint.git \u0026\u0026 cd flatpak-builder-lint\n```\n\nThen the project can be run with:\n\n```sh\nuv run --all-groups --frozen -q flatpak-builder-lint --help\n```\n\nDependencies can be added to removed with `uv add` and `uv remove` while\n`uv lock` will regenerate the lockfile. `uv lock -P` can be used to\nupgrade a specific package or `uv lock -U` to upgrade everything.\n\nThe following Python dependencies are installed and needed to run the\nproject: `jsonschema, requests, requests-cache, lxml, sentry-sdk,\nruamel.yaml, publicsuffixlist` and `PyGObject`. Additionally `setuptools`\nis necessary to build the project. `dunamai` is used to generate a\nversion from the git commit, since no tags or releases are done, in\nabsence of which it will default to the version of the last tag made.\n\n### Formatting and Linting\n\n[Ruff](https://docs.astral.sh/ruff/installation/) is used to lint and\nformat code. [MyPy](https://mypy.readthedocs.io/en/stable/getting_started.html)\nis used to check Python types.\n\nA set of pre-commit hooks are provided to automate the formatting and\nlinting:\n\n```sh\nuv run --frozen -q pre-commit install\n```\n\nTo uninstall:\n\n```sh\nuv run --frozen -q pre-commit uninstall\n```\n\nOr run individually:\n\n```sh\nuv run --frozen -q ruff format\n```\n\n```sh\nuv run --frozen -q ruff check --fix --exit-non-zero-on-fix\n```\n\n```sh\nuv run --frozen -q mypy .\n```\n\n### Tests\n\n[Pytest](https://docs.pytest.org/en/stable/getting-started.html) is used\nto run tests.\n\n```sh\nuv run --frozen -q pytest -vvv\n```\n\nAn additional Flat manager test can be run when modifying code relying\non the flatmanager check. The test is meant to be run on CI and not\nlocally. If it is being run locally, it must be run from the root of the\ngit repository using\n\n```sh\n./tests/flatmanager.sh\n```\n\nTo avoid cleanup run as:\n\n```sh\nNO_CLEAN_UP=1 ./tests/flatmanager.sh\n```\n\nIntegration tests are best suited to be run in CI\n\n```sh\nuv run pytest -m integration -vvv\n```\n\nTo write tests for manifest checks, recreate a minimal Flatpak builder\nmanifest with the cases to check against and put it in `tests/manifests`.\nThen add the test using it (or modify the existing tests) in\n`tests/test_manifest.py`.\n\nSimilarly to add a test for builddir check, recreate the `metadata`,\ncataloge, metainfo, desktop files as needed and put them in a\nsubdirectory of `tests/builddir`. Then add the test in\n`tests/test_builddir.py`. There are helper functions in\n`tests/test_builddir.py` to emulate a flatpak-builder build directory\nusing the source files.\n\nPlease avoid adding binary files that aren't readable.\n\n### Development environment\n\nA development environment is also available as a docker container. To\nuse it to run tests or for linting execute the below from the root of the\nrepository:\n\n```sh\n./docker/build.sh\n```\n\nThis gives an active shell inside the container with all the necessary\ntools available and any changes made are available once the container\nis exited. The same environment can also be used from the docker images\npublished to GitHub if rebuilding the latest isn't necessary:\n\n```sh\ndocker run -it --rm --entrypoint= -v $(pwd):/mnt:Z -w /mnt ghcr.io/flathub-infra/flatpak-builder-lint:latest bash\n```\n\n## Usage\n\n```\nflatpak-builder-lint\n\nA linter for Flatpak manifests and build artifacts primarily\ndeveloped for Flathub\n\npositional arguments:\n  {appstream,manifest,builddir,repo}\n                        Type of artifact to lint\n\n                          appstream expects a MetaInfo file\n                          manifest  expects a flatpak-builder manifest\n                          builddir  expects a flatpak-builder build directory\n                          repo      expects an OSTree repo exported by flatpak-builder\n\n  PATH                  Path to the artifact\n\noptions:\n  -h, --help            Show this help message and exit\n  --version             Show the version number and exit\n  --exceptions          Skip errors added to exceptions. Exceptions must be submitted to Flathub\n  --exceptions-repo     Repo key for remote exception lookups from Flathub. Omitting merges all repo keys; supplying a value merges '*' and that key.\n  --user-exceptions     Path to a JSON file with exceptions\n  --appid               Override the app ID with this app ID\n  --cwd                 Override the path parameter with the current working directory\n  --ref                 Override the primary ref detection with this ref\n  --gha-format          Use GitHub Actions annotations in CI\n  --janitor-exceptions  Enable reporting of stale exceptions to linter repository\n  --debug               Enable debug logging\n\nPlease report any issues at https://github.com/flathub-infra/flatpak-builder-lint\n```\n\n[uv]: https://docs.astral.sh/uv/getting-started/installation/\n[flatpak_setup]: https://flathub.org/setup\n\n## Documentation\n\nA list of errors and warnings and their explanations are available in the\n[Flatpak builder lint page](https://docs.flathub.org/docs/for-app-authors/linter).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fflathub-infra%2Fflatpak-builder-lint","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fflathub-infra%2Fflatpak-builder-lint","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fflathub-infra%2Fflatpak-builder-lint/lists"}