Contributing Flatpaks to Bluefin#

1. Upstream to Flathub#

Bluefin does not host its own Flatpak repository. All graphical applications must first be published on Flathub. To contribute a new Flatpak:

• Ensure your application meets Flathub’s technical and legal requirements.
• Prepare a Flatpak manifest and test local builds using flatpak-builder.
• Submit your application to Flathub by forking the flathub/flathub repository, creating a new branch, adding your manifest and required files, and opening a pull request against the new-pr branch. Follow the submission guide.
• Respond to reviewer feedback and iterate as needed. Once approved, your app will be published on Flathub and available to Bluefin users.

2. Flatpak Quality and Maintenance#

Maintain your Flatpak by following Flathub’s maintenance guidelines. This includes updating runtimes, responding to build failures, and ensuring metadata quality. Applications that pass all quality checks are more likely to be featured both on Flathub and in downstream curated stores like Bazaar.

Managing System Flatpaks in Bluefin#

System-wide Flatpaks in Bluefin are managed through configuration files that list the Flatpak application IDs to be installed by default:

• /etc/ublue-os/system-flatpaks.list for standard system Flatpaks
• /etc/ublue-os/system-flatpaks-dx.list for developer mode Flatpaks

These files define the default set of applications installed on all Bluefin systems. To propose changes (add, update, or remove Flatpaks):

1. Edit the relevant list file in the Bluefin repository (system-flatpaks.list or system-flatpaks-dx.list) and add or remove Flatpak IDs as needed. Each line should contain a single Flatpak app ID, for example:
   ⧉

   app/org.mozilla.firefox
   app/org.gnome.Calculator
   

2. Submit a pull request with your changes. Maintainers will review and merge as appropriate.

During system provisioning or updates, Bluefin installs or updates all Flatpaks listed in these files using the following logic:

flatpak remote-add --if-not-exists --system flathub https://flathub.org/repo/flathub.flatpakrepo
xargs flatpak --system -y install --or-update < /etc/ublue-os/system-flatpaks.list
# Developer mode Flatpaks are installed if developer mode is enabled
xargs flatpak --system -y install --or-update < /etc/ublue-os/system-flatpaks-dx.list

For additional curated application bundles (beyond the default set), see the Brewfiles section below.

Managing System Flatpaks in Bluefin#

Brewfiles#

Bluefin provides curated application bundles via Brewfiles, located at /usr/share/ublue-os/homebrew/. These Brewfiles are installable using the bbrew tool and are the recommended way to add extra applications to your system.

Available Brewfiles:

To install a bundle, run:

ujust bbrew

and select the desired Brewfile from the menu.

• Browse all Brewfiles in the Bluefin repository
• bbrew documentation

The full-desktop.Brewfile is the single source of truth for the full set of curated desktop applications previously managed by the now-removed flatpak-extras mechanism.

Installing Extra Flatpaks#

(See above for the new Brewfiles-based workflow. The previous justfile targets for extra Flatpaks are deprecated and no longer available.)

Featuring Flatpaks in Bazaar#

Bazaar’s featured sections and blocklist are now managed via YAML configuration files located at /etc/bazaar/ on Bluefin systems. These files are maintained in the bluefin-branding submodule, which is included in the common repository as a submodule.

• Featured sections: /etc/bazaar/content.yaml
• Blocklist: /etc/bazaar/blocklist.yaml
• Configuration reference: Bazaar config files in bluefin-branding

Editing Bazaar Featured Sections#

Each section (e.g., "Bluefin Recommends", "Browsers", "Media") is defined in content.yaml and contains an appids list specifying which Flatpaks appear in that section. To feature a Flatpak:

1. Ensure the Flatpak is available on Flathub and not present in the Bazaar blocklist (blocklist.yaml).
2. Edit content.yaml and add the Flatpak’s app ID to the appids list of the desired section. For example:
   ⧉

   rows:
     - sections:
         - category:
             title: "Bluefin Recommends"
             appids:
               - org.mozilla.firefox
               - org.gnome.Calculator
               - com.example.YourApp # <-- Add your app here
   

3. Optionally, create a new section if your application fits a new category.
4. Submit a pull request with your changes to the bluefin-branding repository. Bazaar maintainers will review and merge as appropriate.

Bazaar Blocklist Structure#

Bazaar blocklisting is managed via blocklist.yaml, which uses a YAML structure. Blocklisted app IDs are listed under the blocklists key, for example:

blocklists:
  - block:
    - com.visualstudio.code
    - com.visualstudio.code-oss
    - com.vscodium.codium
    - com.vscodium.codium-insiders
    - com.jetbrains.CLion
    - com.jetbrains.DataGrip
    - com.jetbrains.GoLand
    - com.jetbrains.IntelliJ-IDEA-Community
    - com.jetbrains.IntelliJ-IDEA-Ultimate
    - com.jetbrains.PyCharm-Professional
    - com.jetbrains.WebStorm
    - com.jetbrains.PhpStorm
    - com.jetbrains.PyCharm-Community
    - com.jetbrains.Rider
    - com.jetbrains.RubyMine
    - com.jetbrains.RustRover
    - com.google.AndroidStudio
    - io.neovim.nvim
    - org.vim.Vim
    - io.github.zyedidia.micro
    - com.helix_editor.Helix
    - org.gnu.emacs
    - app.devsuite.Ptyxis
    - org.freedesktop.fwupd
    - io.github.kolunmi.Bazaar

Do not add blocklisted app IDs to Bazaar’s featured sections.

For full reference, see the Bazaar config files in bluefin-branding.

Note: Bazaar configuration and blocklist files are now located exclusively under /etc/bazaar/ and managed in the bluefin-branding submodule. Previous locations such as /etc/ublue-os/bazaar/, /usr/share/ublue-os/bazaar/, and config.yaml are deprecated and no longer used.

Lifecycle Management#

Updates#

• Flatpaks are updated automatically from Flathub. When a new version is published on Flathub, Bluefin systems will receive the update during the next system Flatpak update cycle.
• To update a Flatpak’s version, update it on Flathub. No changes are needed in Bluefin unless the app ID changes or the app is removed.

Removals#

• To remove a Flatpak from Bluefin’s default install, delete its entry from the relevant system Flatpak list file and/or from Bazaar’s content.yaml.
• To remove a Flatpak from Flathub, follow Flathub’s end-of-life process.

Blocklisting#

• Some Flatpaks are explicitly excluded from Bazaar via the YAML-based blocklist.yaml file. Do not add blocklisted app IDs to Bazaar’s featured sections.
• The blocklist is at /etc/bazaar/blocklist.yaml and uses a YAML structure. Blocklisted app IDs are listed under the blocklists key (see above for example).
• Ensure your app is not listed in blocklist.yaml before proposing it for Bazaar.

Maintenance Responsibility#

• Flatpak maintainers are responsible for keeping their applications up to date on Flathub.
• Bluefin maintainers review and merge changes to system Flatpak lists and Bazaar configuration.

Contributor Checklist#

• Publish your Flatpak on Flathub and ensure it meets all quality guidelines.
• Propose changes to Bluefin’s system Flatpak lists if you want your app installed by default.
• Propose changes to Bazaar’s /etc/bazaar/content.yaml to feature your app in the curated store.
• Ensure your app is not blocklisted in /etc/bazaar/blocklist.yaml.
• Respond to review feedback from Bluefin and Bazaar maintainers.

For more information, consult the Flathub documentation and Bluefin’s contribution guidelines.

References:

• Flathub Documentation
• Bluefin Common Repository
• Bluefin Branding Submodule - Bazaar Config
• Bluefin Contribution Guidelines
• Ask Bluefin Knowledge Base

All version and configuration information is kept up to date in the bluefin-branding submodule and common repository. Always consult the latest files and documentation before contributing.

For further questions, visit the Ask Bluefin Knowledge Base or open an issue in the relevant repository.