Table of Contents:
This guide will give an overview of the Apertis reference Flatpak runtimes, as well as creating, signing, and publishing your own runtimes and applications.
Apertis provides a reference Flatpak runtime, available in two variants:
org.apertis.headless.Sdk: A basic runtime with some common libraries that headless applications may use.
org.apertis.hmi.Sdk: A larger runtime for graphical applications, based on the headless one but with additional packages included that are generally needed by graphical applications.
Each pair above links to the manifest file used to build it, containing a full list of the explicitly included packages. (For guidance on interpreting the package lists, see the Adding Packages section below.)
In addition, a version of GNOME
Fonts using the HMI runtime
is available as a demo, under the name
In order to install the runtimes and/or demo, the Flatpak repository must first be set up:
$ flatpak --user remote-add apertis https://images.apertis.org/flatpak/repo/apertis.flatpakrepo
You can then proceed with the installation:
$ flatpak --user install \ org.apertis.headless.Platform \ org.apertis.headless.Sdk \ org.apertis.hmi.Platform \ org.apertis.hmi.Sdk \ org.apertis.hmi.gnome_font_viewer
During installation you may be prompted for which version to install. Due to incompatibilities between flatpak versions, it is highly recommended you select the version corresponding to the Apertis version your system is running (see Versioning for more information).
Finally, the demo application can be run by executing the following command:
$ flatpak run org.apertis.hmi.gnome_font_viewer
The reference runtimes and included demos are built for each stable Apertis release, starting with v2022. Use of a runtime version older than the host version is supported, such as running or developing with runtime v2022 on Apertis v2023. However, using runtimes newer than your Apertis release (e.g. using v2023 on a v2022 system) is not supported, because newer runtimes may depend on Flatpak functionality that is not available in older Apertis releases.
The reference Apertis runtimes are built using apertis-flatdeb, which is able to create a new Flatpak runtime using packages from the Apertis distribution.
apertis-flatdeb can be installed on an Apertis system via
sudo apt install apertis-flatdeb.
apertis-flatdeb encourages the use of a particular filesystem layout for runtimes (the concepts of “suites” will be explained further below):
suites/directory, containing YAML files describing “suites”, which are essentially just the package lists that a runtime will be using.
runtimes/directory, containing YAML files corresponding to the runtime variants that will be built.
flatpak-buildermanifest files for applications that can be built alongside the runtimes.
All of these should be under a single main directory, which we will henceforth refer to as the working directory.
As mentioned above, suites determine the package lists that will be used for the
runtime to build on. Each file inside
suites is named
RELEASE determines the Apertis version you’re targeting. For instance, to use
Apertis v2022 packages, the suite file would be
As for the actual content, it is highly recommended to simply reuse the [suite files used in the reference runtime], which already contain everything needed for an Apertis runtime. Simply take the same file and rename it to follow the desired Apertis version. (The files contents should not need to be changed.)
Once the suite is configured, we need to generate a base chroot for flatdeb to work in. From the working directory, please execute the following command:
$ flatdeb --build-area=$(pwd)/flatdeb-builddir \ --ostree-repo=$(pwd)/flatdeb-builddir/ostree-repo \ --suite=<SUITE_NAME> --arch=<TARGET_ARCHITECTURE> \ base
This will create a
flatdeb-builddir subfolder containing a file named
base-<SUITE_NAME>-<TARGET_ARCHITECTURE>.tar.gz containing the base rootfs
needed for future operations. If you delete this file, or want to target a
different Apertis version, you will have to run the above command again.
The majority of the logic in creating a runtime goes in
NAME should be the
id_prefix of the runtime. This
file lists out the packages that go into the runtime and the details of any
special steps taken during its creation. The manifest files used to build the
Apertis reference runtime are available for use as
The files are in the following format:
The ID Prefix
id_prefix determines this runtime’s IDs. The platform will be named after the
prefix followed by
.Platform, and the SDK will be similar but using
For instance, in the above example, the platform and SDK names would be
pre_apt_script contains code that will be run before
apt installs any of
the runtime’s packages, and
post_script will be run towards the end of the
runtime creation process (after all packages are installed). In addition, both
of these are available specifically for
.Sdk by placing them
sdk: maps, respectively. These scripts can be used
to modify the final system layout or modify the repositories before packages are
installed; in particular, this is used by the reference runtime to enable
development packages in the SDK (see Enabling Development
add_packages will add the packages listed inside to both the
Sdk variants, and the
add_packages key inside
sdk: will add
packages only to the SDK.
add_packages_multiarch is similar but will attempt
to install the packages for all architectures given, rather than just the
primary architecture. For instance, given the above example:
sdk-package4 will be
installed for all the architectures explicitly given to
Platform will generally contain shared libraries that applications will
need at runtime, but they can also include executables the application would
depend on, or even resources for making the application more useful.
SDK-specific packages will likely include development libraries and headers, the build system and compilers, and optionally additional development tools.
Enabling Development Repositories
The suite files that the reference runtime uses only enable the
repository by default, not the
development repository. This ensures that no
GPLv3+ packages end up in the base platform, but it also means one cannot
install development packages into the SDK. In order to resolve this,
pre_apt_script as mentioned above can be used to enable
the development repositories for the SDK only:
This will enable the development repositories, then update the package lists.
overlays takes a list of paths and copies their contents onto the runtime’s
rootfs towards the end of the build process (after
post_script is run),
providing a simple mechanism to add custom files to the final runtime. The paths
are all resolved relative to the location of the runtime file, i.e. if the above
runtimes/org.test.yaml, the first path used would be
runtimes/common-overlay. Platform- and SDK-specific overlays can be added by
placing the overlays key in the
sdk: maps, respectively.
Given the following filesystem tree:
runtimes/ org.test.yaml common-overlay/ etc/ test.conf platform-overlay/ usr/ bin/ platform-util sdk-overlay/ usr/ bin/ sdk-util
the above YAML would add the following files to the platform:
and to the SDK:
Extending Another Runtime
Sometimes, it may be desired for one runtime to extend another; for instance,
the HMI reference runtime extends the headless runtime. In order to achieve
this, there is one more key that can be used at the top level:
extend:. As an
example, consider a new runtime
org.test.extended, based on
YAML file would contain:
This will merge in all of
org.test.yaml’s definitions, according to the
- All packages from the base are available for use.
pre_apt_scripts in the base will be run before the ones in the current runtime, and any
post_scripts in the base will be run after.
- Any overlays in the base will be applied before the ones in the current runtime, so that the ones in the base can be overwritten.
apertis-flatdeb also has support for adding custom extensions to the runtime.
The semantics of the keys in the extension definition are identical to the
Flatpak metadata file, thus please consult the
under the section
The suite files used by the reference runtime have
fontconfig to be installed in the platform and SDK
runtimes. If this is not the case, remove
persist_font_cache: from your suite
Building the Runtime
Once the runtime recipe is complete, you can build the runtimes using the following commands:
$ flatdeb --build-area=$(pwd)/flatdeb-builddir \ --ostree-repo=$(pwd)/flatdeb-builddir/ostree-repo \ --suite=<SUITE_NAME> --arch=<TARGET_ARCHITECTURE> \ runtimes runtimes/<RUNTIME_NAME>.yaml
This will build both the
Sdk runtimes, which will be stored in
an OSTree repository under
By default, both of these will have their branch set to
SUITE_NAME. If another
branch is desired, it can be set by passing
If building for the host’s architecture, then
--arch= can be omitted.
If the runtime should include packages from multiple architectures (e.g. an
arm64 runtime supporting running armhf binaries), then those packages should be
listed in the
add_packages_multiarch section. In order to
specify which architectures should be used, you can pass multiple architectures
--arch. For instance, given the following example:
$ flatdeb ... --arch=arm64,armhf runtimes runtimes/<RUNTIME_NAME>.yaml
arm64 will be used as the architecture, but any packages in
add_packages_multiarch will also have
armhf variants installed.
In order to speed up a more limited build, two sets of options are available:
- Only the platform or SDK can be built by passing
- The building of the source code and debug info extensions can be skipped using
--no-debug-symbols, respectively. These extensions are needed for debugging, but otherwise they can take a significant amount of extra time to build.
All of these options should be placed before the
One can test local changes to packages that will be installed into the runtime
--override-package. The format for this is:
flatdeb [...] runtimes --override-package=PACKAGE=DEB
(Note that, unlike the above options,
--override-package comes after
PACKAGE specifies the name of the package to replace, and
DEB is the path to
the local package to use. For instance,
--override-package=meson=packages/meson.deb would result in any installations
meson in the runtime using the local
packages/meson.deb instead of the
version in the repos.
This option cannot be used to add new packages, nor can it be used to replace
dependencies, i.e. passing
--override-package with a package name not
directly listed in
add_packages: value will do nothing.
Applications are generated from a more classic
manifest, the only notable
points here being that:
runtimemust mention your runtime as
- The same goes for
sdkwhich should contain
- The same goes for
runtime-versioncan be unset, as apertis-flatdeb will automatically set it to be the runtime’s version (e.g.
As described in Layout, the manifest should be located under a new
The application is built by executing the following command:
$ flatdeb --build-area=$(pwd)/flatdeb-builddir \ --ostree-repo=$(pwd)/flatdeb-builddir/ostree-repo \ --suite=<SUITE_NAME> --arch=<TARGET_ARCHITECTURE> \ app --app-branch=<SUITE_NAME> apps/<APP_NAME>.yaml
Once the command completes, the application will be available from the same
OSTree repository already containing the runtime, under
As with runtimes, if building for the host’s architecture, then
--arch= can be
For the sake of completion, it is worth noting that, when building applications,
apertis-flatdeb is a thin wrapper over the upstream
with some useful additional functionality:
- When run in the same location as a runtime, any local runtime builds will be used for the built applications. In other words, one can make a change to the runtime, then any application builds from the same location will have the runtime’s changes applied.
- As mentioned previously, if the app’s
runtime-versionis unset, it will automatically be set to the appropriate version.
In other words,
flatpak-builder can run application builds directly, but using
apertis-flatdeb brings various enhancements and makes it possible to use a
single tool for both runtime and application builds.
Single-file Flatpak “bundles” (not to be confused with the concept of application bundles) can be created with flatdeb:
$ flatdeb --build-area=$(pwd)/flatdeb-builddir \ --ostree-repo=$(pwd)/flatdeb-builddir/ostree-repo \ --suite=<SUITE_NAME> --arch=<TARGET_ARCHITECTURE> \ app --app-branch=<SUITE_NAME> apps/<APP_NAME>.yaml
This will create files inside of
<APP_NAME>*.-<TARGET_ARCHITECTURE>-<SUITE_NAME>.flatpak , which can then be
flatpak install, e.g.:
$ flatpak install com.test.Test-amd64-v2022.flatpak
Execution and Debugging on Target Devices
In order to run and/or debug Flatpak applications on the target device, the Flatpak must already have been built into a bundle file and installed onto the host system.
Aside: Target SSH Access
Note that these steps are not specific to Flatpaks but must be done in order to proceed with the remaining debugging steps.
SSH key is required to allow connecting from SDK to the target without
requesting password. The following commands will generate a SSH RSA key-pair
(using the legacy PEM format) and copy the generated public key to the target.
In the example, it assumes that the address of the target device is
192.168.0.100. Accept the default settings so as not to require any password
to access the target board.
$ export TARGET_HOST=192.168.0.100 $ ssh-keygen -t rsa -m PEM Generating public/private rsa key pair. Enter file in which to save the key (/home/user/.ssh/id_rsa): Created directory '/home/user/.ssh'. Enter passphrase (empty for no passphrase): Enter same passphrase again: Your identification has been saved in /home/user/.ssh/id_rsa. Your public key has been saved in /home/user/.ssh/id_rsa.pub. The key fingerprint is: SHA256:Yd3+gA4ZpWUczdlFKFlaNsyQfET09+UJF5LZYNAaFrI user@apertis The key's randomart image is: +---[RSA 2048]----+ | o=B=^&=o| | *++XBB+.| | =Eo =+ .+| | . + + o.=| | S . o .o| | o o | | . . | | | | | +----[SHA256]-----+ $ ssh-copy-id user@$TARGET_HOST
Setting Up GDB on the Target
Before starting to debug the target, we need to ensure that the application’s SDK, containing gdbserver, is installed on the target device:
$ ssh user@$TARGET_HOST "flatpak install <RUNTIME_NAME>.Sdk/<TARGET_ARCH>/<SUITE_NAME>"
Installing Debug Symbols
To get proper backtraces under GDB, the debug symbols from the runtime and applications must first be installed onto the host system:
Debug symbols for the runtime and SDK can be installed via:
$ flatpak install <RUNTIME_NAME>.Sdk.Debug/<TARGET_ARCH>/<SUITE_NAME>
Debug symbols for the application itself can be installed by locating the Flatpak bundle file
<APP_NAME>.Debug-<TARGET_ARCHITECTURE>-<SUITE_NAME>.flatpakand installing it via
Launching the Application
For the following example steps, we assume that the Flatpak application and its
runtimes are installed on the host system, that you are using a SSH key-pair to
login to your target device, and that the address of the device is stored in the
TARGET_HOST environment variable.
To install the Flatpak on the target, run:
$ scp \ flatdeb-builddir/<APP_NAME>-<TARGET_ARCHITECTURE>-<SUITE_NAME>.flatpak \ user@$TARGET_HOST: $ ssh user@$TARGET_HOST \ "flatpak install <APP_NAME>-<TARGET_ARCHITECTURE>-<SUITE_NAME>.flatpak"
Once that is complete, the target can be run in gdb:
$ ssh user@$TARGET_HOST \ "flatpak run -d --command=gdbserver \ <APP_NAME>/<TARGET_ARCHITECTURE>/<SUITE_NAME> \ :1234 /app/bin/<MAIN_APPLICATION_BINARY>"
Then, gdb can be started on the host system and connected to the target:
$ flatpak run -d --command=gdb <APP_NAME>/<TARGET_ARCHITECTURE>/<SUITE_NAME> (gdb) target remote :1234
Note that this requires the target board to allow incoming connections on the
port passed to
gdbserver (the above example used
Starting with Apertis v2022dev2, Flatpak includes the ability to distribute application bundles verified with ed25519 signatures.
The current implementation is a technology preview and it is expected to stabilize during the release cycles leading to the v2022 stable release. The prototype is already available in Apertis as documented here, but it may be subject to potentially incompatible changes during the upstream review process.
This signature system relies on OSTree’s library functions. Therefore, the key generation and storage process is identical to what is described in the System updates and rollback design document.
Flatpak application signatures occur on several levels:
- single commits
- whole repositories
- single-file bundles
Please note, however, that GPG signatures, the upstream default, are disabled on Apertis. It is still possible to pull from GPG-signed repositories, but those signatures won’t be verified. Similarly, it is not possible to sign flatpak applications using GPG when using Apertis.
Creating signed flatpak applications
The simplest way to create a signed flatpak is to use
--sign=<SECRETKEY> command-line argument, where
<SECRETKEY> is the
base64-encoded secret Ed25519 key. This ensures the OSTree commit and summary
are properly signed:
flatpak-builder --repo=myrepo --sign=m8/rp9I9ax2w81yujZyeXTfZlbeBjEBUPQSQKo14iHgHdrzpKYH6xvL83midrFNeMrU4QBtk4jZ+x2veQoP4oQ== build-dir org.example.sampleapplication.yaml
For more advanced usage, the same command-line option can also be used with the following flatpak commands:
These commands allow one to create Ed25519-signed commits from an unsigned repository or single-file bundle, or to create signed bundles as explained below.
Multiple occurrences of the
--sign option are allowed in to order to permit
multiple signatures of each object.
More details about those commands are available in the Flatpak documentation.
Publishing signed Flatpaks
Publishing a repository
When distributing several applications and their runtimes, it can be useful to publish the whole repository.
Hosting the repository
Depending on whether
flatpak-builder is used, the
repository will be stored in the folder specified by either the
--repo command-line argument, respectively. In its simplest form, hosting
the repository can simply be placing its contents as-is on a remote server.
However, uploading the data to the server is somewhat sensitive: during the
upload process, some files in the OSTree repository may be present before the
files they in turn depend on. Thus, the repository may turn out to be unusable
until the upload completes. In order to remedy this, a tool named
can be used, which will upload the repository files in a well-defined order to
the remote server over SSH.
ostree-push, it’s recommended to pull down the contents of the
remote repository before building the runtimes or apps in question via
$ ostree init --repo=repo $ ostree remote --repo=repo --sign-verify=ed25519=inline:<PUBLICKEY> \ --if-not-exists origin https://example.org/flatpak/repo $ ostree pull --repo=repo --depth=-1 --mirror origin <REFS>...
<PUBLICKEY> is the base64-encoded public Ed25519 key, and
contains the references that will later be uploaded. For instance, for the
org.test.Platform/x86_64/v2022 and app
pull command would be used:
$ ostree pull --repo=repo --depth=-1 --mirror origin \ runtime/org.test.Platform/x86_64/v2022 \ app/org.test.Platform/x86_64/v2022
After the build process is completed, the newly built items can be uploaded via the following:
$ ostree-push --repo repo ssh://<USER>@<HOST>:<PORT>/<PATH> <REFS>...
<HOST>is the SSH server to connect to
<USER>is the user to sign in as on the server
<PORT>is the port the SSH server is running on (
:<PORT>may be omitted entirely if the default port of 22 is used)
<REFS>is identical to as mentioned previously for
Continuing the previous example, if we now wanted push the same refs to
/var/public/repo on an SSH server
2022, logging in as
archive, the command used would be the following:
$ ostree-push --repo repo ssh://firstname.lastname@example.org:2022/var/public/repo \ runtime/org.test.Platform/x86_64/v2022 \ app/org.test.Platform/x86_64/v2022
ostree-push is run, the summary file (essentially an index file for the
repository) will need to be rebuilt. This can be accomplished by running the
following on the server containing the repository:
$ flatpak build-update-repo --sign=<SECRETKEY> <REPO>
<SECRETKEY> is the base64-encoded secret Ed25519 key and
<REPO> is the
path to the repository. One can pass
--generate-static-deltas in order to make
pulling from the repository faster, at the expense of taking up more storage
space on the host system.
Making the repository publicly accessible
In order for the repository to easily be added to client systems, a .flatpakrepo file can be used.
The only difference here compared to the linked documentation is that the
GPGKey=... line must be replaced with
<PUBLICKEY> is the base64-encoded public Ed25519 key.
Such a .flatpakrepo file could be:
[Flatpak Repo] Title=Sample Repository Url=https://example.org/flatpak/repo Homepage=https://example.org/flatpak Comment=Sample Flatpak repository signed with Ed25519 Description=This Flatpak repository provides applications signed with Ed25519 Icon=https://example.org/flatpak/icon.svg SignatureKey=B3a86SmB+sby/N5onaxTXjK1OEAbZOI2fsdr3kKD+KE=
Making a single application accessible
One way to make installing a single flatpak application from a repository convenient is to use .flatpakref files. Those files include all necessary information for flatpak to be able to install and update the application.
Exactly as it is done with with
.flatpakrepo files, using
SignatureKey=<PUBLICKEY> instead of
GPGKey=... will instruct flatpak to
enable Ed25519 signature verification for this repository.
This line will instruct flatpak to add the corresponding configuration keys to the remote and perform signature verification when installing and/or updating this application.
Such a .flatpakref file could be:
[Flatpak Ref] Name=org.example.sampleapplication Title=Sample application from our example repo Url=https://example.org/flatpak/repo RuntimeRepo=https://example.org/flatpak/example.flatpakrepo IsRuntime=false SignatureKey=B3a86SmB+sby/N5onaxTXjK1OEAbZOI2fsdr3kKD+KE=
Publishing a single-file bundle
The concept of “bundles” within Flatpak is unrelated to the Apertis-specific term “application bundles”. For clarity, the concept described in this section will be referred to as a “single-file bundle”.
Flatpak applications can also be distributed as
which can be created using the
flatpak build-bundle command. As previously
mentioned, these bundles can be signed by adding the
to the command invocation:
flatpak build-bundle --sign=m8/rp9I9ax2w81yujZyeXTfZlbeBjEBUPQSQKo14iHgHdrzpKYH6xvL83midrFNeMrU4QBtk4jZ+x2veQoP4oQ== myrepo example.bundle org.example.sampleapplication
However, when publishing a signed flatpak bundle, the corresponding public key has to be stored in a location easily accessible to the final user for signature verification, as the bundle file itself is signed and doesn’t provide any mean to retrieve the associated public key.
Installing a signed flatpak
Configuring a remote repository
If the repository publisher provides a
.flatpakrepo file including the public key,
then no action is needed other than running
flatpak remote-add <REPONAME> <REPOFILE>.
However, if such a file is not available, one must add the
command-line option to the
flatpak remote-add command in order to provide
either the public key directly, or a file containing the public key:
--sign-verify=ed25519=inline:<PUBLICKEY>is used to directly specify the public key needed to verify this repository
--sign-verify=ed25519=file:<PATH>can be used to point flatpak to a file containing a list of public keys (base64-encoded, one key per line), among which at least one can be used to verify signatures for this repository
flatpak remote-add example example.flatpakrepo
flatpak remote-add --sign-verify=ed25519=inline:B3a86SmB+sby/N5onaxTXjK1OEAbZOI2fsdr3kKD+KE= example https://example.org/flatpak/repo
--sign-verify occurrences are allowed in order to specify as many
public keys as needed. This can be useful when a new signature key is being
deployed, while the old one is still in use: by specifying both the old and the
new key, users can make sure at least one of those will be able to verify the
signatures. That way, once the old key is revoked and only the new one is used
for signing the repository, the corresponding remote will keep working as
This option can also be added when using the
flatpak remote-modify command.
Installing a signed application
Similarly to the process of using
.flatpakrepo files, when installing a single
application using a
.flatpakref file including the public key, no additional
action is needed. Flatpak will automatically verify Ed25519 signatures using the
provided public key:
flatpak install --from example.flatpakref
When the application is installed from a previously configured repository, signature verification is also automated, as long as the corresponding public key has been imported into the remote’s configuration:
flatpak install org.example.sampleapplication
If the public key has not been previously imported into the remote’s
configuration, one can also use the
--sign-verify command-line option:
flatpak install --sign-verify=ed25519=inline:B3a86SmB+sby/N5onaxTXjK1OEAbZOI2fsdr3kKD+KE= org.example.sampleapplication
Installing a signed bundle
Flatpak bundles are not installed from a repository like most flatpak
applications, but from a single, optionally signed, file. As there is no
repository configuration to import public keys from, the user needs to specify
the relevant public keys using the
--sign-verify command-line option as stated
flatpak install --sign-verify=ed25519=inline:B3a86SmB+sby/N5onaxTXjK1OEAbZOI2fsdr3kKD+KE= --bundle example.bundle
This option works the same way with both
flatpak build-import-bundle and
flatpak install commands.
Building Flatpaks on GitLab CI
ci-flatdeb-builder provides a premade GitLab CI pipeline generator that streamlines the process of building, testing, and publishing Flatpak runtimes and apps located on GitLab.
In order to use ci-flatdeb-builder, the target repository’s “CI/CD configuration
should to be set to point to
REPO_URL points to the ci-flatdeb-builder repository (for upstream
Apertis, this will be
https://gitlab.apertis.org/infrastructure/ci-flatdeb-builder). In addition,
the following CI/CD
should be set on the repository:
ARCHIVE_SECRET_FILEshould be a file variable containing an SSH private key that can be used to access the server where the build results should be uploaded to. If this value is not set, build results will not be published.
FLATPAK_PRIVATE_KEYshould be ed25519 public and private keys, respectively, that will be used to sign the built Flatpaks. If these are not set, then no Flatpaks built will be signed. These keys should be identical for a single OSTree repository, i.e. multiple GitLab projects pushing to one OSTree repository should use the same keys.
In order to generate a new private key, use the following command:
$ openssl genpkey -algorithm ed25519 -outform DER | base64
The corresponding public key can then be retrieved via:
$ echo THE_GENERATED_PRIVATE_KEY | base64 -d | openssl pkey -outform DER -pubout | base64
In addition, instead of being set per-repository, these values can be set on a
GitLab group, which will result in
ci-flatdeb-builder being run on all the individual repositories within. This is
preferred if there is a dedicated GitLab group containing exclusively Flatpaks.
(Currently, on Apertis GitLab, this is enabled on the
With this setup, every push and merge request will result in Flatpak runtimes and applications being built.
The following additional CI variables may be optionally set, if their defaults are not suitable:
UPLOAD_HOST: The SSH server where build results should be published to (i.e. the server that
ARCHIVE_SECRET_FILEis used to access).
UPLOAD_ROOT_TEST: The paths on
UPLOAD_HOSTwhere the resulting Flatpak repositories will be placed for stable and test builds, respectively.
REMOTE_URL_TEST: The URLs where build results will be accessible at after being uploaded to
CI_FLATDEB_BUILDER_REPO: The URL of the GitLab repository containing
ci-flatdeb-builder.yaml; i.e., the
REPO_URLthat was used above in the “CI/CD configuration file” value.
CI_FLATDEB_BUILDER_REVISION: The Git revision of the ci-flatdeb-builder repo to use. (This defaults to
main; if changed, the
mainin the “CI/CD configuration” URL should also be changed to match.)
The defaults are set within the
ci-flatdeb-builder.yaml file described above;
you may view the contents directly to observe how they are set for your
downstream ci-flatdeb-builder variant and determine whether or not any changes
would be needed. (In general, the only reason these would need to be changed is
if uploading to a non-default OSTree repository or testing a custom version /
fork of ci-flatdeb- builder.)
ci-flatdeb-builder supports two different repository layouts:
- If flatdeb runtimes are available under
runtimes/, then flatdeb will be used to build them, as well as any apps under
- Otherwise, any
*.yamlfiles in the root directory will be built via flatpak-builder.
In many cases, some configuration will be required in order to customize
ci-flatdeb-builder for your Git repository, which can be specified in a file
flatdeb-builder.yaml in the repository root. A sample configuration file
Stable Branch Naming
This determines the naming scheme for the repository’s stable branches:
main_only(the default): the
masterbranch is the Git repository’s stable branch. Built Flatpaks will have the version
stablewhen built from the stable branch or
testwhen built from any other branch.
versioned: any Git branch
apertis/*is treated as the repository’s stable branch, and the built Flatpaks will use the Git branch name portion after
apertis/as its version. For instance, given
apertis/v2022, any Flatpaks built from it will have the version
If the Git branch name does not match
apertis/*, but the branch is in a merge request to a branch that does match, then the MR’s target branch name will be used. For instance, if
apertis/v2022is forked to as
wip/user/fix-things, v2022 will be used.
main_only is intended for “rolling”-style repositories where there
is at most a single stable version, and
versioned is for repositories where
the Flatpak versions should go hand-in-hand with Apertis releases.
When building Flatpaks apps, this will install any needed dependencies, such as
runtimes, from the remote at the given URL. The value of
sign determines what
signing system the remote uses:
ed25519(the default) is the signing system used by Apertis.
gpgis the standard signing system used in the Flatpak world (e.g. by Flathub). (Note that, technically, Apertis does not currently support GPG signatures, thus this option is simply an alias for
nonewill treat the remote as being unsigned.
Limiting Supported Architectures
By default, all Flatpak runtimes and apps are built for aarch64, arm, and
x86-64. This can be limited by setting
supported_architectures to the
architectures that should actually be used. For instance, the following will
only build on x86-64 and arm64, but not arm:
You can define multiple test jobs that are run after builds but before publish.
The content of
tests is a mapping of test names to test definitions,
targets: This lists Flatpak runtimes (under the
runtimeskey) and applications (under the
appskey) built from this pipeline that the tests need to access. (Note that listing an application will automatically include the runtime the application needs without listing said runtime explicitly.)
command: A command to run that will perform the tests.
Before the test command runs, a Flatpak remote named
deps will be added,
containing all of the dependencies of the runtimes and apps in
The test command will have the following environment variables available:
$OSNAME: Set to
apertis, but downstream distros may change this to a different value.
$FLATPAK_BRANCH: The version / branch of the runtimes and/or apps built (see #stable-branch-naming for more information on what this is).
$FLATPAK_ARCH: The architecture the Flatpaks are built for (one of
$DEBIAN_ARCH: The Debian-compatible architecture name corresponding to
$TARGETS_REPO: Path to an OSTree repository containing the runtimes and apps in
Publishing a .flatpakrepo
This will automatically use the given
template to create
the published OSTree repository directory. The template can reference two
different variables that will be substituted inside:
$REMOTE_URLis the URL to the OSTree repository.
$FLATPAK_PUBLIC_KEYis the public key that the repository is signed with. (If the repository is unsigned, this will be empty.)
Flatpak reference documentation: https://docs.flatpak.org/