Flatpak CI

Requirements

Meson. Feel free to adapt to Autotools or other build system, however we rely on Meson for the templates.
GtkApplication/GApplication based. So it's possible to have different app-ids.

Basic CI

The main goal here is to make sure our CI runs for every commit and MR and the project is buildable using the same base across GNOME, the Flatpak env.

For that, use the following template and replace the variables with the appropriate variables for your project.

include: 'https://gitlab.gnome.org/GNOME/citemplates/raw/master/flatpak/flatpak_ci_initiative.yml'

flatpak:
    image: 'registry.gitlab.gnome.org/gnome/gnome-runtime-images/gnome:master'
    variables:
        MANIFEST_PATH: "build-aux/flatpak/org.gnome.NautilusDevel.yml"
        FLATPAK_MODULE: "nautilus"
        APP_ID: "org.gnome.NautilusDevel"
        RUNTIME_REPO: "https://nightly.gnome.org/gnome-nightly.flatpakrepo"
        BUNDLE: "nautilus-dev.flatpak"
    extends: '.flatpak'

The template will do the following:

Build with meson build inside a nightly Flatpak environment.
Install with ninja install in /app prefix.
Run tests with ninja test with a xvfb-run mocked display inside a Flatpak environment. The mocked display has a resolution of 1024x768.

If you need to change the configure args that will be passed into meson, you can do so by defining a CONFIG_OPTS variable.

    variables:
        CONFIG_OPTS: >-
            --buildtype=debugoptimized
            -Dwerror=true

Flatpak bundle for every MR and commit

The main goal is to create Flatpak bundles so people can install and run them.

Create a Flatpak package/bundle and export it
Create a GitLab artifact to save the generated bundle for 14 days

The template will create a Flatpak bundle with flatpak build-bundle and the runtime pointing to the value of RUNTIME_REPO variable. Once the build is done you will see a widget that exposes the artifacts of the job in the MR and that can download the generated Flatpak bundle.

Flatpak builds on every commit to your main branch

The nightly builds can be published to GNOME Nightly Flatpak Repository, by adding the following job. It will publish the build on the master, main or mailine branch, but only if it the branch is marked as protected in gitlab.

nightly:
  extends: '.publish_nightly'
  # assuming your job in named 'flatpak'
  dependencies: ['flatpak']
  needs: ['flatpak']

Saving build and test logs & cache builds

If the CI fails, we need a way to retrieve the logs. For this we use the artifacts tool of GitLab too. The provided template exports the meson-logs.txt and the testlog.txt files as part of the artifacts.

Final gitlab-yaml file template

Here is the resulting template, but it is recommended to try doing it step-by-step.

include: 'https://gitlab.gnome.org/GNOME/citemplates/raw/master/flatpak/flatpak_ci_initiative.yml'

flatpak:
    image: 'registry.gitlab.gnome.org/gnome/gnome-runtime-images/gnome:master'
    variables:
        MANIFEST_PATH: "build-aux/flatpak/org.gnome.NautilusDevel.yml"
        FLATPAK_MODULE: "nautilus"
        APP_ID: "org.gnome.NautilusDevel"
        RUNTIME_REPO: "https://nightly.gnome.org/gnome-nightly.flatpakrepo"
        BUNDLE: "nautilus-dev.flatpak"
    extends: '.flatpak'

nightly:
    extends: '.publish_nightly'
    # assuming your job in named 'flatpak'
    dependencies: ['flatpak']
    needs: ['flatpak']

Parallel installation

For GLib & Gtk+ based apps we need to generate a different dbus id, so different versions can be installed and ran alongside. For that, we created the concept of "profiles" in the building phase. This is a bit tricky and also needs to be done all at once for the major part.

The stable profile will be used for distributions and stable versions, and the development profile will use a different id for the application itself, the icons, the installation path, services, etc.

First, let's add basic support for profiles in the root meson.build file.

Root meson.build

if get_option('profile') == 'Devel'
  name_suffix = ' (Development Snapshot)'
elif get_option('profile') != ''
  profile = get_option('profile')
  name_suffix = get_option('profile')
else
  profile = ''
  name_suffix = ''
endif

# Replace AppName with your app name
application_id = 'org.gnome.AppName@0@'.format(profile)

# We will use this inside the actual code to give visual hints that
# it's a development version
conf.set_quoted('PROFILE', profile)

# Used to put in the about dialog the git commit that was used to build
config_h = declare_dependency(
  sources: vcs_tag(
    command: ['git', 'rev-parse', '--short', 'HEAD'],
    fallback: get_option('profile') != 'default'? 'devel' : 'stable',
    input: configure_file(
      output: 'config.h.in',
      configuration: conf
    ),
    output: 'config.h'
  )
)

And make sure to add the config_h dependency to your project dependencies. Usually in the executable command:

executable(
...
...
dependencies: [
    config_h,
    gtk
  ],
)

Lastly, add a meson option in the meson_options.txt file for the profile:

option(
  'profile',
  type: 'combo',
  choices: [
    'default',
    'development'
  ],
  value: 'default'
)

Icons handling

To install icons with the proper name change to the following on your data/meson.build:

icondir = join_paths('icons', 'hicolor', 'scalable', 'apps')
install_data(
  join_paths(icondir, '@0@.svg'.format(application_id)),
  install_dir: join_paths(datadir, icondir),
  rename: '@0@.png'.format(application_id)
)

icondir = join_paths('icons', 'hicolor', 'symbolic', 'apps')
install_data(
  join_paths(icondir, 'org.gnome.AppName-symbolic.svg'),
  install_dir: join_paths(datadir, icondir),
  rename: '@0@-symbolic.svg'.format(application_id)
)

If you are providing a Nightly variant of your application icon, make sure to name it "org.gnome.AppNameDevel.svg" (replace "AppName" by your application name). This way the code above will assign the desired icon to each profile.

Desktop file handling

The desktop file name has to match the dbus id, so we need to recreate it based on the profile selected.

For that, in the data/meson.build create the desktop file with:

desktop_conf = configuration_data()
desktop_conf.set('icon', application_id)
desktop = i18n.merge_file(
  'desktop',
  input: configure_file(
    input: files('org.gnome.AppName.desktop.in.in'),
    output: 'org.gnome.AppName.desktop.in',
    configuration: desktop_conf
  ),
  output: '@0@.desktop'.format(application_id),
  install: true,
  install_dir: desktopdir,
  po_dir: po_dir,
  type: 'desktop'
)

Replace "AppName" by your application name.

And in the desktop.in.in file change to the following:

Icon=@icon@

AppData handling

Similar to the desktop file, need to take application_id into account. Create the appdata file with:

appdata_conf = configuration_data()
appdata_conf.set('appid', application_id)
appdata = i18n.merge_file(
  'appdata',
  input: configure_file(
    input: files('org.gnome.AppName.appdata.xml.in.in'),
    output: 'org.gnome.AppName.appdata.xml.in',
    configuration: appdata_conf
  ),
  output: '@0@.appdata.xml'.format(application_id),
  install: true,
  install_dir: join_paths(datadir, 'metainfo'),
  po_dir: po_dir
)

Replace "AppName" by your application name.

In the xml.in.in file change to the following:

<id>@appid@.desktop</id>

Service handling

Every GLib app registers as a service too. So similar to desktop file and appdata, let's take into account the application id:

service_conf = configuration_data()
service_conf.set('appid', application_id)
service_conf.set('bindir', join_paths(prefix, bindir))
configure_file(
  input: 'org.gnome.AppName.service.in',
  output: '@0@.service'.format(application_id),
  configuration: service_conf,
  install_dir: servicedir
)

Replace "AppName" by your application name.

In the service.in file change the following line:

Name=@appid@

Shell search provider handling

Most of core apps have a shell search provider, we need to take into account the application id too for this.

search_provider_conf = configuration_data()
search_provider_conf.set('appid', application_id)
search_provider_conf.set('profile', profile)
configure_file(
  configuration: search_provider_conf,
  input: files('org.gnome.AppName.search-provider.ini.in'),
  install_dir: join_paths(datadir, 'gnome-shell', 'search-providers'),
  output: '@0@.search-provider.ini'.format(application_id)
)

And in the search provider .ini.in file change the values to the following:

DesktopId=@appid@.desktop
BusName=@appid@
ObjectPath=/org/gnome/AppName@profile@/SearchProvider

Replace "AppName" by your application name.

Flatpak manifest handling

Simply change the app id to the matching app id of the selected profile, for example:

"app-id": "org.gnome.AppNameDevel",

And in config-options of your module section add:

"config-opts": [
    "-Dprofile=Devel"
],

For the stable flatpak branch, change the id to the regular one and the profile to the stable one.

Application handling

Now we need to handle inside the code itself the proper id. Now you can include the config.h generated with the selected ID from the build. In your GtkApplication implementation:

In the startup vfunc, make sure to apply the correct application id:

gtk_window_set_default_icon_name (APPLICATION_ID);

In the creation of the GtkApplication, make sure to pass the correct id too:

g_object_new (APP_NAME_TYPE_APPLICATION,
              "application-id", APPLICATION_ID,
              "flags", G_APPLICATION_HANDLES_COMMAND_LINE | G_APPLICATION_HANDLES_OPEN,
               NULL);

For your preferences dialog, make sure to set the proper icon name:

gtk_window_set_icon_name (GTK_WINDOW (preferences_window), APPLICATION_ID);

Same for the about dialog:

program_name = g_strconcat (_("App Name"), NAME_SUFFIX, NULL);
gtk_show_about_dialog (window ? GTK_WINDOW (window) : NULL,
                       "program-name", program_name,
                       "logo-icon-name", APPLICATION_ID,
                       ...,
                       NULL);

And lastly, if you have a Shell search provider, pass the correct id too:

g_dbus_interface_skeleton_export (G_DBUS_INTERFACE_SKELETON (self->skeleton),
                                  connection,
                                  "/org/gnome/AppName" PROFILE "/SearchProvider", error);

Adding a visual hint for development

The goal is that the person installing a profile knows that it's a development version right away, including in case errors are reported with an screenshot. For that we will add an style to the app when running in devel mode.

In your application window code:

    if (g_strcmp0 (PROFILE, "") != 0)
    {
        GtkStyleContext *style_context;

        style_context = gtk_widget_get_style_context (GTK_WIDGET (window));

        gtk_style_context_add_class (style_context, "devel");
    }

Which assumes that if there is a profile set, it's going to be for development. Otherwise, no styling is set. The devel CSS style class is provided by gtk+ itself.

FAQ

Why not use the flatpak-builder one liner?

flatpak-builder --repo=repo app org.gnome.Manifest.json

This almost does what we would want, but not quite. If you build this way it will always try to fetch your modules from the source specified in the manifest, but we want to use our local checkout instead. This is fine if you only build the master branch but MRs need to be able to change the source to their checkout.

To achieve this we use the --stop-at=module argument which will build all of the dependencies up to your module from the manifest. Then we take over and need to install the application ourselves. This is why your config s CONFIGURE_ARGS variable needs to be kept in sync with your module's config options in the manifest.

A previous version of the template had some extra review and stop_review jobs, what happened to those?

They have been deprecated and replaced by a simpler feature that provides the same function. It should simplifies both the template setup, and the backend setup needed to run the previous jobs. For more you can refer to this commit

DevOps with Flatpak

Flatpak CI

Requirements

Basic CI

Flatpak bundle for every MR and commit

Flatpak builds on every commit to your main branch

Saving build and test logs & cache builds

Final gitlab-yaml file template

Parallel installation

Root meson.build

Icons handling

Desktop file handling

AppData handling

Service handling

Shell search provider handling

Flatpak manifest handling

Application handling

Adding a visual hint for development

FAQ