The goal of these requirements is to ensure that the applications hosted on Flathub are safe to use and integrate well in the desktop experience.

If you have any further questions please join #flatpak on ircs:https://chat.freenode.net

All content hosted on Flathub must allow for redistribution and the license must be correct in the appdata file. Non-redistributable files can be downloaded at install time using the extra-data source type.

The application ID needs to be unique to the developer of the application and the convention for this is to be based on the reverse-DNS of the project, e.g. org.project.Application. Application IDs however do not support all the same characters as DNS such as - or elements starting with a digit. The convention for these is to replace - with _ and prefix leading digits with _ e.g. org.7-zip would turn into org._7_zip.

The manifest must be at the top level and named after the application ID with the extension .json. All patches and data files required also go in the repository.

At this point, Flathub is only hosting stable application releases not development snapshots. Therefore, the manifest should refer to tarballs or git tags and must not be the tip of a branch.

In case you build from a git tag, please specify both the tag name and the commit id, like so:

   "tag": "1.0.4",
   "commit": "cdfb19b90587bc0c44404fae30c139f9ec1cca5c"

This makes the build reproducible, since a tag can otherwise change its value over time. You can also use only a commit, but specifying a tag name if there is one is good for readability.

Flathub always builds in the flatpak branchname "stable" and it always passes --default-branch=stable so you don’t need to specify a branch key but if you do it must be "stable".

Flathub requires that you build against an sdk that is itself hosted on Flathub. The same goes for sdk extensions that may be required to build your application. The easiest way to see what runtimes are currently available is to install the flathub remote and run:

flatpak remote-ls --runtime --show-details flathub

In most cases the selected runtime will not contain all of the dependencies you need so you will have to build and bundle them along with your application. The only thing to note is they should match the requirements here such as its license and also take care to check the build directory for unnecessary files that can be added to cleanup for smaller package sizes.

There are a few dependencies that are common between more than a few packages so to share the maintenance burden these have been collected in a repository: flathub/shared-modules. These are intended to be used as a submodule like so:

git submodule add https://github.com/flathub/shared-modules.git

Then from within your manifest you can include the .json files directly:

"modules": [
  "shared-modules/SDL/SDL-1.2.15.json",
  {
    "name": "foo"
  }
]

It is acceptable to use patches to fix issues when necessary but they should all be sent upstream.

Currently flathub is focused on graphical desktop applications and not CLI/TUI applications.

All applications in flathub must ship with appstream data, a desktop file, and an application icon.

See https://www.freedesktop.org/software/appstream/docs/index.html

• must pass appstream-util validate-relax and should pass appstream-util validate-strict.

• must include a description

• must include releases with versions and should contain changelogs.

• should contain OARS information: https://hughsie.github.io/oars/

• If not upstream’d it must have the CC0-1.0 metadata_license.

See https://standards.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html

• must pass desktop-file-validate.

• must contain 64x64 and 128x128 sizes for app stores.

• should be scalable SVGs or provide high resolution PNGs

The Flatpak sandbox is still a work in progress but we would still like to limit permissions as strictly as we can while still having functional software. See man flatpak-metadata for an overview of permissions.

These are simply allowed as they are necessary for base functionality:

• --share=network
• --share=ipc
• --socket=x11
• --socket=wayland
• --socket=pulseaudio
• --device=dri

You should not grant --socket=system-bus or --socket=session-bus unless it is a development tool. Use the --log-session-bus and --log-system-bus flags to flatpak run to track down usage.

By default you are granted access to --own-name=$your_app_id any ownership beyond that is usually questionable but there are exceptions such as org.mpris.MediaPlayer2.$media_player_name.

Talk permissions are largely unrestricted but always try to use the minimum subset needed.

Ideally software uses the Portals for file choosers but it is often necessary to grant further access which is acceptable but should be limited. Some further recommendations:

• If you need access to an XDG directory use the variables such as xdg-music or xdg-run/foo. (see man flatpak-metadata)

• Always append :ro if write access is not needed.

• If an application hardcodes a path in $HOME and you don’t grant home access you can use --persist and it will map the $HOME directory to your private directory e.g. --persist=.mozilla. If the application takes args to set config/data dirs then use them.

• Do not attempt to retain configs from non-flatpak installations. While possible it is recommended that flatpak installs stay self-contained.

• If an application uses $TMPDIR to contain lock files or shared files with other process create a wrapper script that sets it to $XDG_CACHE_HOME.

While not ideal you can use --device=all for accessing devices like controllers.

All reviews happen via comments on PR’s. We also have labels to make note the status of a PR which is useful when no actions have happened over a long period.

Once a PR has been reviewed the steps for reviewers to take after:

1. Create a new repository matching the application-id under the flathub organization
2. Push their latest commits to it (optionally rebase the commits)
3. In Settings > Branches mark master as protected to preserve history
4. Add the author of the PR in Settings > Collaborators & Teams > Collaborators
5. Close the PR linking to this new repository

A script to aid in steps 1, 2, and 5 can be found here: https://gist.github.com/TingPing/62714aea793856e42c7c556dc46caf49

Note this script does require installing gh via npm and does require some configuration.

Here are some documentation on how to maintain your application once it is accepted into flathub: App Maintenance