GNOME Build Metadata

Overview

The GNOME Build Metadata repository is where the GNOME release team manages build metadata for building the:

• GNOME OS
• GNOME Flatpak runtimes
• GNOME OCI images for CI

Getting started

Using GNOME OS

For an overview of the project, visit the GNOME OS website.

If you want to install GNOME OS, follow the appropriate guide for your device and setup:

• Typical desktop and laptop computers
  • Dual Booting with another operating system - We don’t support this setup, but you can use it at your own risk
• Phones - Experimental support for OnePlus 6 and Fairphone 5

Be sure to check out the User Guide afterwards.

Quick start: The latest ISO nightly can be downloaded from https://os.gnome.org/download/latest/gnome_os_x86_64.iso and restored onto a USB drive

Using GNOME Flatpak runtimes

If you’d like to use GNOME Flatpak runtimes, please head to the Flatpak documentation on the GNOME runtimes and Building a flatpak.

Quick start: flatpak install flathub org.gnome.Sdk//master

Using GNOME OCI images

If you’d like to use GNOME OCI images, please see the CI registry at quay.io, to understand which images are available see the Published Build Outputs and OCI Contributing.

Quick start: podman pull quay.io/gnome_infrastructure/gnome-build-meta:gnomeos-nightly

Releases

gnome-build-meta tracks the releases of GNOME. See the GNOME release calendar.

Contributing

To contribute to the GNOME Flatpak runtime, GNOME OS or GNOME OCI images, see the contribution guide to get started, and the debugging guide for common troubleshooting steps.

You can also read the markdown source of the documentation in docs

The repository can be found as gnome-build-meta on GNOME gitlab and it has an official read-only mirror on Github.

Installation Guide

Warning

Experimental software

You can run GNOME OS on real hardware now, with a few caveats: Hardware support is limited, there is no dedicated security team and some features are missing. This is bleeding edge, in-development software, and not recommended for daily usage if you’re not a developer.

Hardware Support

The standard GNOME OS Nightly ISO can be installed and should just work on many computers, depending on how well the hardware components are supported by Linux. We keep a public document of hardware support submitted by users, you can consult it to see if your hardware is supported or help us expand it. We want to improve our hardware support, so if you run into issues with your hardware please report them here.

We also experimentally support some Android phones. Installation on those devices requires special steps and some things may not work, so please consult the linked documentation.

Prepare USB Drive

1. Download the latest GNOME OS ISO

2. Plug in a USB drive and select it in GNOME Disks

3. In the ⋮ menu select Restore Disk Image…, open the ISO and click Start Restoring…

   Warning

   This erases all data on the USB drive.

Boot from USB

In order to run GNOME OS you need UEFI to be enabled, and secure boot to be disabled.

1. Reboot into BIOS options and disable secure boot
2. Boot from the USB drive
3. Choose GNOME OS Nightly in the menu

Install

1. Go through initial setup and create a user

2. If your destination disk contains data, erase it in GNOME Disks using Format disk… and selecting No Partitioning

   Warning

   This erases all data on the disk.

3. Upon logging in, a window will have proposed to install GNOME OS. Choose Install now

4. Select the disk to install to, and press Install

5. If the installer gives you a recovery key, your data is encrypted. Write the key down on a different device

6. You can then continue using GNOME OS

Now you should have a working GNOME OS setup on real hardware. Since GNOME OS is quite different from other Linux operating systems you should take a look at the user guide.

Note on Dual-Booting

Dual-booting GNOME OS is not recommended or officially supported. If you need to dual-boot GNOME OS with another OS, follow the manual dual-boot instructions.

Install GNOME OS on an Android phone

Installation

Supported phones

This has been only tested on the OnePlus 6 and the Fairphone 5. It may work on other phones that are supported by mainline linux kernel.

Downloading

Download the u-boot build for your device from the Tauchgang project. There are no stable releases yet, download the build for your device from the latest pipeline

Download the GNOME OS aarch64 ISO

Create the disk to flash with: (FIXME: update to-raw.sh)

sudo systemd-repart --empty=create --size=auto --sector-size=4096 --architecture=arm64 --definitions=utils/repart.raw.d/ --image=gnome_os-aarch64.iso userdata.img

(replace gnome_os-aarch64.iso with the actual filename)

Flashing to the phone

You first need to unlock the bootloader. The postmarketOS wiki has nice instructions on how to unlock the bootloader.

You need to clear the dtbo partition, to allow for booting non-Android systems.

fastboot erase dtbo

flash the boot image with:

fastboot flash boot boot.img

Then flash the userdata image with:

fastboot flash userdata userdata.img

Then reboot the phone:

fastboot reboot

Known bugs, workarounds

Selecting time zone in GNOME Initial Setup

Cannot choose a timezone via the textbox

Clicking on the map to select your timezone, should be working instead.

“Next” button is off-screen

Moving the window to the left, should expose the “Next” button. Alternatively, select your time zone, press “Previous”, then “Next”, then press Enter on the on-screen keyboard.

Sound does not work

Not sure why yet.

No modem

For the modem to still work after suspend without restarting ModemManager, you need to use --test-quick-suspend-resume to its command line. For this, run systemctl edit ModemManager.service and write:

[Service]
ExecStart=
ExecStart=/usr/bin/ModemManager --test-quick-suspend-resume

If the modem does not appear in other cases, maybe try to restart ModemManager.

No SIM

sudo qmicli -d qrtr://0 --uim-get-card-status

Look for the application ID. Then use it in:

sudo qmicli -d qrtr://0 --uim-change-provisioning-session='slot=1,activate=yes,session-type=primary-gw-provisioning,aid=XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX'

You can create unit in /etc/systemd/system to run this command. You should probably make it start after tqftpserv.service.

For example

[Unit]
After=tqftpserv.service
Before=ModemManager.service
StartLimitBurst=10

[Service]
Type=oneshot
RemainAfterExit=yes
ExecStart=qmicli -d qrtr://0 --uim-change-provisioning-session='slot=1,activate=yes,session-type=primary-gw-provisioning,aid=12:34:56:78:90:AB:CD:EF:01:23:45:67'
Restart=on-failure
RestartSec=1s

[Install]
WantedBy=multi-user.target

SMS and calls

Install Chats (aka Chatty) and Calls from flathub. RCS messages do not work, if you have multiple SIM on the same phone number, you might not get all messages.

(Calls were not yet tested).

No camera

Still needs patches that are not mainlined yet.

USB host

It has to be switched manually through debugfs, which is not accessible on GNOME OS due to lockdown. Thus it is not possible to switch to host mode.

Modem wants authentication when starting

Something to fix, the polkit configuration is probably wrong for ModemManager.

Device crashes when the screen turns off

Some devices periodically crash when the screen turns off (either due to inactivity or when suspending). The notification LED lights up and turns solid white. After a bit, the phone enters “QUALCOMM CrashDump” mode.

wifi connection keeps dropping

Occasionally, the wifi chipset restarts and briefly drops the current wifi connection. Actively using the connection (e.g: ssh connection, downloading sth.) seems to increase the frequency of disconnects. Bluetooth connections do not drop at all.

plymouth does not work

Plymouth tries to launch, renders incorrectly and exits (first few seconds of bootup). Does not affect the boot process.

RTC clock is incorrect

RTC clock shows current time as ‘Epoch + time since GnomeOS was installed’.

[kawaiicvnt@retard ~]$ timedatectl status
        Local time: Wed 2026-01-07 21:00:01 EET
    Universal time: Wed 2026-01-07 19:00:01 UTC # Actual date
          RTC time: Fri 1970-01-02 22:45:29     # Epoch + time since install

RTC time is not lost between reboots, but there appears to be no RTC available when trying to set the time manually.

Installing GNOME OS manually to dual boot

If you want to try to install GNOME OS on a disk along with another OS (aka dual booting), you can try to install GNOME OS manually.

Overview of the process

We expect that here that you are running GNOME OS’ live image.

1. Make some space on the disk. You will need 10GB + size of user data.
2. If your ESP is small, you will need to create an XBOOTLDR partition.
3. Create the A partitions and copy /usr and its verity.
4. Copy the kernel to ESP or XBOOTLDR
5. Copy boot chain to your ESP
6. Reboot and force shim fallback

Note on using systemd-repart

systemd-repart can create and format partitions. In order to do it that you need to create a configuration directory. Then put some *.conf files. Then give the configuration to systemd-repart with --definitions=<path>. Typically, it will not write to the disk until you add --dry-run=no. But do dry run first to make sure what it is going to do.

Look at man pages for systemd-repart(8) and repart.d(5) for more information.

Creating an XBOOTLDR

You need at least 500MB in your ESP, or 1G if you plan to use NVidia proprietary drivers. We recommend 1G in either case.

You can use a repart.d configuration file such as:

[Partition]
Type=xbootldr
Format=vfat
SizeMinBytes=1G
SizeMaxBytes=1G

You need to run this configuration through systemd-repart.

Creating initial /usr

You can use repart.d config files:

• /usr/lib/repart.d/20-usr-verity-A.conf
• /usr/lib/repart.d/21-usr-A.conf

Copy those files to your own repart.d definition directory and edit them to add CopyBlocks=auto on each of them.

You need to run this configuration through systemd-repart. You can run both configurations for this section and previous section at once.

Copy the kernel

Mount the ESP or the created XBOOTLDR. Then copy /var/lib/gnomeos/installer-esp/EFI/Linux/gnomeos_*.efi into /EFI/Linux of the mounted disk.

Copy the boot chain

Mount the ESP (if not already mounted). You need to copy files from /usr/share/factory/efi into the ESP. If you already have a Linux distribution installed on the machine, you can skip files in /EFI/BOOT.

Reboot

Make sure to boot the disk, not an entry¹, in order to trigger the fallback from shim. That will show a blue screen, this means that it is creating the boot entry for GNOME OS. Then you can choose to boot that entry.

Verify the disk encryption

When not installing with the installer, the disk will still be encrypted of a TPM is available. However you need to verify a few things

Set the recovery key

There is no propery recovery key set, but there is a password set: ihavenotsetarecoverykey. We recommend that you set a proper recovery key instead.

systemd-cryptenroll --recovery-key --wipe-slot password

Keep the recovery key somewhere safe!

Verify pcrlock

If you run the following:

cryptsetup luksDump /dev/disk/by-partlabel/root

Check in the output that for the token of type systemd-tpm2, there is tpm2-pcrlock: true. If it is true. You’re grand.

If not, first check if you TPM does support pcrlock:

/usr/lib/systemd/systemd-pcrlock is-supported

If that does not says “yes”, your TPM or firmware is too old. If it says yes, try to enroll it.

/usr/lib/systemd/systemd-pcrlock remove-policy
/usr/lib/systemd/systemd-pcrlock make-policy --location=770 --pcr=0+1+2+3+4+5+7+11+13+14+15
systemd-cryptenroll --wipe-slot=tpm2 --tpm2-device=auto --tpm2-pcrs='' /dev/disk/by-partlabel/root

1. UEFI can store multiple boot entries. They typically give a path to the EFI binary to call, and its parameters. Each disk also has a default boot, which is something like EFI\BOOT\BOOT*.EFI. If you want to boot that default, you need to boot the disk. So if you list UEFI boot entries, you will see names of operating systems as well as name of disks. Here we want to boot the disk the first time, so it will add the missing entry for GNOME OS. ↩

User Guide

Installing software

GNOME OS does not have a traditional package manager, but you can install software in a variety of ways. Graphical applications are available via flatpak and are easily installed from GNOME Software. Podman, toolbox and distrobox are also available.

You can also use snap after enabling it and rebooting:

updatectl enable --now snapd apparmor

Update via command line

System updates are handled by systemd-sysupdate. GNOME Software should work just fine for that, but you can also do updates via terminal like so:

updatectl update

After that you can directly reboot into the new image.

Use an older version of the operating system

There are always 2 versions of the operating system kept installed. If you need to use an older version, you can choose an older version from the menu at start-up.

Install an older version of the operating system

You can install an even older version if it is still available to download using updatectl, for example version nightly.1234:

updatectl update host@nightly.1234

List all available versions for your system:

updatectl list host

Enable development tooling and utilities

If you want to install the development toolchain of GNOME OS you can do so by enabling the following System Extensions. These include compilers, headers, along with common utilities used for GNOME development, such as flatpak-builder, GNOME Builder and so on.

sudo updatectl enable devel --now

Enable extra codecs on the host system

The host system does not come with support for some patent-encumbered codecs by default. The system video player will not be able to play these formats, neither will thumbnails be generated for them. You can enable support for these codecs by enabling an optional extension.

sudo updatectl enable codecs-extra --now

Flatpak applications do not need this to open the same files.

Enable the Nvidia driver

GNOME OS ships with the upstream open source drivers for Nvidia graphics cards, which are enough for light use but have subpar performance and don’t support features like CUDA. If you want the best performance or need to use features like CUDA and OptiX, you should enable the Nvidia driver extension like so:

sudo updatectl enable nvidia-driver --now

After rebooting, you should be using the Nvidia driver.

Note

This extension only supports RTX 1600/2000 series or newer cards.

Boot into older versions

If an update breaks something, you can always boot into an older version. You can do this quickly by pressing any key during boot to enter the menu, and then choosing a different version from the list.

Updating firmware

Before applying a firmware update, you need to unlock the firmware PCR values. This will automatically recreate a pcrlock policy on next boot

sudo /usr/lib/systemd/systemd-pcrlock unlock-firmware-code
sudo /usr/lib/systemd/systemd-pcrlock unlock-firmware-config

Re-enroll tpm2 if needed

If you update your firmware or reset the uefi settings, you might be asked to manually unlock your hard drive, instead of happening automatically. This is because the state of the machine has changed without the OS knowing about it. In such case you will need to re-enroll the tpm2 values for the updated firmware keys. (We are exploring ways to make this easier in the future)

sudo /usr/lib/systemd/systemd-pcrlock remove-policy
sudo /usr/lib/systemd/systemd-pcrlock make-policy --location=770 --pcr=0+1+2+3+4+5+7+11+14+15
sudo systemd-cryptenroll --wipe-slot=tpm2 --tpm2-device=auto /dev/disk/by-partlabel/root

Troubleshooting

See our debugging guide for common troubleshooting steps.

Debugging

Pre-requisites

Disable secureboot

If you are using Secure Boot, you will need to disable it in order to enable debugging options in the OS.

Enable Boot Menu

When booting the machine, you can hold the Spacebar to see the persistent Boot Menu that comes from systemd-boot. You can press ? or h to see all the available options. Pressing e will allow you to edit the kernel command line (cli) arguments (also commonly referred to as boot arguments).

Failed boot

Here are some tips and tricks for diagnosing and debugging a failed boot.

First you should check if you can get a VT (Virtual Terminal) by using the control-alt-f2 shortcut. You can also use f3-f6 to get additional terminals. control-alt-f1 and control-alt-f7 are reserved for the display server.

Boot to the working version and read the logs of the failing one

If the latest version does not boot, you can inspect the logs by restarting and selecting the older one.

GNOME OS keeps two versions of the system around at all times. You can select the previous one from the boot menu as mentioned above.

Once you are in a working version you can inspect the failed build with the following command:

journalctl --boot=-1

GDM does not start / crashes on a loop

If GDM or Shell is crashing or you don’t get into a session for some reason you can override the systemd target unit with the following kernel cli argument.

systemd.unit=multi-user.target

Boot without System Extensions

If you have installed a System Extension (sysext) that is causing issues you can disable all extensions by selecting the “Safe Mode” boot option.

Alternatively, you can add the following argument to the command line yourself:

gnomeos.safe-mode=1

If you do not have the nvidia feature enabled, you can also just add:

systemd.mask=systemd-sysext.service

Enable Debug Shell

Enabling the debug-shell will give you a root console you can drop into. By default, it will appear in tty9 (control + alt + f9).

systemd.debug-shell=1

If the system fails to get into the debug shell, you can add the following to get a shell inside the initrd.

systemd.debug-shell=1 rd.systemd.debug-shell=1

You can also connect the debug shell on a serial console. (Useful for VMs).

ttyS0 is usually the default serial console name. Depending on the Virtualization solution you are using, the name might be different (ex: ttyAMA0 or ttyhvc0).

systemd.debug-shell=ttyS0 rd.systemd.debug-shell=ttyS0

Disable plymouth

If plymouth is causing issues for whatever reason you can disable it in the following way.

First remove quiet and splash from the default kernel command line arguments and then add the following:

plymouth.enable=0

Enable systemd debug logging

To enable more verbose logging of systemd itself add the following.

systemd.log_level=debug systemd.log_target=console

You can also forward the journal to the console

systemd.journald.forward_to_console=1

For more detailed and systemd specific information, refer to the detailed documentation.

Disable gnome-initial-setup

You can do this by either adding InitialSetupEnable=false in /etc/gdm/custom.conf or by adding gnome.initial-setup=0 to the kernel command line arguments

Other

Force Toggle GNOME Shell animations

Animations may be disabled in certain situations, such as when using software rendering for Graphics, such as llvmpipe.

However, its sometimes needed to be able to toggle them on demand for testing. This can be done easily from the lookingglass interface in GNOME Shell.

Simply type alt+f2 to bring up the command runner, then type lg. Then enter the following global.force_animations = true

Show the Tour dialog again

If you want to trigger the Tour dialog on the next login, you can do so by reseting its settings key.

gsettings reset org.gnome.shell welcome-dialog-last-shown-version

Inspect the Kernel Config

You can inspect the config of the kernel with the following command

zcat /proc/config.gz | less

Inspect the System

Here are a couple of files with metadata that can help you identify the versions of the software running. They can also be attached in bug reports.

The /usr/lib/os-release file will print the version of the OS currently running, along with the commit it was build from and date.

The /usr/manifest.json file contains the version of the source of every module in the system.

With updatectl features you will get a list of all the available features and their state.

Last, you can find the installed versions of the OS with updatectl list host.

Hardening of a GNOME OS installation

GNOME OS tries to be secure, but also not to be a hassle for non developers and non tech savy people. So some of the security features are not fully enabled. And those who need it need to do a bit of extra configuration.

Securing the disk encryption

GNOME OS will automatically encrypt the root filesystem with the TPM if this is found. However the default encryption configuration is lax in order to avoid friction. Users that want proper full disk encryption (for example for work computers) need to harden their installation. They can either:

• Set a PIN and enable dictionary attack protection.
• Enable secure boot and eventually lock PCRs to the firmware.

It is of course possible to use both approaches. But only one is needed.

Note

At this point, homed is not used by default, and we are not encrypting user accounts separatly.

Setting the dictionary attack lockout

In order to protect your PIN from brute force attacks, you should enable dictionary lockout on your TPM. This is not yet handled by systemd.

If you fail any of the setup commands, you might need to wait 24 hours or clear your TPM.

Caution

Trying to change the configuration of the lockout using the wrong authorization will trip the lockout. And you will need to wait 24 hours or clear the TPM. So be sure to use the right authorization value to avoid losing time.

Set an authorization value

The authorization value will be used to reconfigure the lockout hierachy. If you do not set it, an attacker could just disable the protection.

First check if there is an authorization value that was set by another operating system.

run0 tpm2_getcap properties-variable

Is lockoutAuthSet 1? If so and you do not know the authorization value, you should clear your TPM. And then re-enroll the TPM keys.

If it is not set, you can set one with:

python3 -c "import secrets, string; print(''.join(secrets.choice(string.ascii_letters + string.digits) for _ in range(32)))" | run0 tee /etc/credstore/tpm.lockout
run0 tpm2_changeauth -c lockout file:/etc/credstore/tpm.lockout

Or if it set and you know the value, you can changed it with:

run0 tpm2_changeauth -c lockout -p myoldpassword file:/etc/credstore/tpm.lockout

Configuring the dictionary attack lockout

You can specify:

• the number of tries with -n
• the duration it takes to recovery from a failed reconfiguration with -l
• the duration it takes to be able to boot your system again after being locked with -t

For example if you want to have 10 minutes timeouts and 32 tries:

run0 tpm2_dictionarylockout -s -n 32 -t 600 -l 600 -p file:/etc/credstore/tpm.lockout

Do not make time too long or the number too stricts. It might make your system trip more often, and very long to recover. For indication the default values are usually 32, 1000, 1000.

Clear lockout on reboot

If you plan to reboot faster than the timeout you gave, and the number of tries is small, you should clear the lockout on successful boots. You also probably want to clear the lockout automatically after using recovery key.

For that, add in /etc/systemd/system/clear-lockout.service:

[Service]
Type=oneshot
ExecStart=tpm2_dictionarylockout -c -p file:${CREDENTIALS_DIRECTORY}/tpm.lockout
ImportCredential=tpm.lockout

[Install]
WantedBy=multi-user.target

Then enable it.

systemctl enable clear-lockout.service

Enroll a pin on the TPM

By default we encrypt your hard drive if there’s a tpm2 device available. The long term plan is to use systemd homed to encrypt user data, but until then you can replace the unattended luks decryption with a tpm2+pin key in luks using the following command.

sudo systemd-cryptenroll --wipe-slot=tpm2 --tpm2-with-pin=true --tpm2-device=auto /dev/disk/by-partlabel/root

Enabling secure boot

You can enable secure boot by enrolling the keys we provide.

Warning

This might soft brick your computer if you do not know what you are doing. And even if done correctly, this might prevent firmware updates in some cases.

• Go in your firmware (BIOS) settings and find the Secure Boot options
• Select “setup mode” or “clear keys”. You might need to enable Secure Boot for the option to be available
• Save your changes and reboot
• The boot loader will provide two new entries. Select “default”. This contains also the Microsoft keys which means it will allow firmware to be loaded from option ROMs. “private” will forbid those, which is a bad idea if you are not sure if you have option ROMs
• Wait 15 seconds.

Once you have enabled secure boot, you can lock the PCRs to that state with:

systemctl enable systemd-pcrlock-secureboot-authority.service
systemctl enable systemd-pcrlock-secureboot-policy.service

Locking firmware to PCRs

You can lock the PCRs to the firmware with the following:

systemctl enable systemd-pcrlock-firmware-code.service
systemctl enable systemd-pcrlock-firmware-config.service

This will disallow firmware update.

uinput, hidraw

Because of Steam, user has access to uinput which can create new input devices, like a keyboard. Applications that get access to /dev/uinput could inject commands into a terminal, and hitchhike a sudo session.

To disable it:

ln -s /dev/null /etc/udev/rules.d/60-steam-input.rules

Some hidraw devices are also given access to users. Those are less of an issue. These are in rules:

• 70-gnomeos-hidraw.rules
• 60-steam-vr.rules

Firewall

The default firewall zone is “lax”. It only blocks some of the system ports. This is not enough in general. You can set the zone of your connection to a stricter zone like “public”, “work”, or “home”. For example:

nmcli connection modify "My Connection" connection.zone "public"

You can also change the zone assigned by default on new network connections:

firewall-cmd --set-default-zone=public

Contributing to GNOME Build Metadata

1. Setting up the build environment

The content of this repository is a BuildStream project. For more information on BuildStream, check out its user guide and reference documentation for all available features and options.

If you’re using GNOME OS as your developer workstation, you can set up all the tools and dependencies you need to build this repository by enabling the devel extension:

updatectl enable devel --now

Alternatively, you can use Toolbox to get a containerized build environment like so:

toolbox create -i registry.gitlab.com/freedesktop-sdk/infrastructure/freedesktop-sdk-docker-images/bst2
toolbox enter bst2

2. Forking and cloning the GNOME Build Metadata repository

First, create a fork of the repo in your account by visiting https://gitlab.gnome.org/GNOME/gnome-build-meta/-/forks/new. Please also see the GNOME Project Handbook for a general GNOME GitLab usage guide. Then, clone the repository to a local directory on your workstation:

git clone git@ssh.gitlab.gnome.org:your-username/gnome-build-meta.git # Adjust your-username to your GNOME GitLab username
cd gnome-build-meta

By default this will clone the master branch of the repository. If you want to contribute a change to a different version, check out the branch for it:

$ git checkout gnome-50

2.1 Branches

• master is where the nightly gnome-build-meta releases originate and should be the target for most development, it tracks the latest nightly versions of GNOME.
• gnome-<series> are stable branches of gnome-build-meta and they each target a corresponding stable branch of GNOME. The branches are created at the beta release of the corresponding GNOME branch. To see the status of the GNOME branches and releases see the GNOME release calendar.
• gnome-<series>-alpha branches are unstable branches of gnome-build-meta, and they may target alpha releases of GNOME and created as necessary.
• <username>/<change summary>, <change summary>, and any other branches are for development, it is recommended to namespace development branches with your username.

See CI Outputs for details on what each branch produces in CI.

3. Create a new development branch

Now create a branch to make your changes in:

# Adjust your-intended-change to describe your intended change
$ git checkout -b your-intended-change

If you need help with your contributions, ask for help in #gnome-os:gnome.org on Matrix.

4. Making changes

You can find definitions for components, their build steps and dependencies under elements/. Elements can depend on other elements and be composed together to build complete targets like the ones in published build outputs. Adding a new component or dependency generally means adding a new BuildStream element and modifying existing ones to include it in its list of dependencies.

We use the Freedesktop SDK as a base for a lot of our components, using a BuildStream junction. This means that some components are shared and changes to those components should be done upstream in the Freedesktop SDK. Such components are prefixed with freedesktop-sdk.bst: when listed as a dependency, so they are easy to spot.

The first build might take a while depending on your workstation’s specs. On a 2025 workstation with a fast SSD, 32 GB of RAM, 24 cores, and a 1 Gb/s internet connection, the first build takes about 25 minutes and requires about 50 GB of disk space. Subsequent rebuilds are much faster and take about one minute from making a change to seeing the change running on the workstation.

First, create a workspace for the component you want to work on; for example for the Linux kernel:

bst workspace open freedesktop-sdk.bst:components/linux.bst --directory ../linux/

For GNOME Shell:

bst workspace open core/gnome-shell.bst --directory ../gnome-shell/

Or for GNOME Settings:

bst workspace open core/gnome-control-center.bst --directory ../gnome-control-center/

Now make the changes you want to make in your workspace, for example in ../linux/ or ../gnome-control-center/. BuildStream will pick up your changes from this workspace automatically after you make them.

How to build, deploy and test depends on which build output you’re contributing to. Follow the dedicated guide for each:

• GNOME OS: see the GNOME OS contribution guide
• GNOME Flatpak runtimes: see the Flatpak runtimes contribution guide
• GNOME OCI images: see the OCI images contribution guide

$ cat > ~/.config/buildstream.conf << 'EOT'
projects:
  gnome-build-meta:
    strict: false
EOT

$ cat >> ~/.config/buildstream.conf << 'EOT'
artifacts:
  override-project-caches: true
source-caches:
  override-project-caches: true
EOT

For individual elements, you can also build them and inspect the result, either by checking out the built artifact to a directory or by dropping into a runtime shell:

bst build core/gnome-shell.bst
bst artifact checkout core/gnome-shell.bst --directory ./gnome-shell-artifact
bst shell core/gnome-shell.bst

You can also get a build shell to inspect the environment. Note that only the specified dependencies are staged; if you need a utility for debugging (vim, strace, etc.) you will have to add them as build-dependencies:

bst shell --build core/gnome-shell.bst

It’s also possible to build for another architecture using QEMU:

bst -o arch aarch64 build sdk/gjs.bst
bst -o arch aarch64 shell --build sdk/gjs.bst

Making changes to documentation

Missing something? This documentation is written in markdown and is kept in the docs/ subdirectory of the repository. We are happy to get more contributions to improve our documentation!

5. Opening a merge request with your changes

Once you have carefully reviewed and tested your changes, you can contribute them upstream. Please also see the GNOME Project Handbook for a general GNOME GitLab usage guide.

5.1 Option 1: Changes to an upstream component

How to do so depends on the individual project you’ve made changes to, since each project has its own contribution conventions and guidelines. For components such as the Linux kernel, GNOME Shell, or GNOME Settings, these are usually described in each project’s repository. If you’ve used bst workspace open, you can find them in the workspace directory you checked out to (e.g. ../linux/ or ../gnome-control-center/).

Once your change has been merged upstream and a new release has been created, the next update_refs job in CI/CD will usually automatically update the references to include the new upstream version with your changes. Once merged, CI/CD will build and deploy new prebuilt published build outputs.

5.2 Option 2: Changes to GNOME Build Metadata itself

If you’ve made a change to GNOME Build Metadata itself, such as adding or modifying a BuildStream element, configuration, or board, you can git add your changes, git commit them, git push them to your fork, and open a merge request by visiting https://gitlab.gnome.org/your-username/gnome-build-meta/-/merge_requests/new?merge_request%5Bsource_branch%5D=my-intended-change (adjust your-username to your GNOME GitLab username and my-intended-change to your branch name).

Be sure to select the correct target branch; the default is master, so if you’re contributing a change to a different version, switch it to that version’s branch, e.g. gnome-50. Fill out the merge request description (it might be helpful to look at recently merged MRs for inspiration), submit it, and someone will review it for you.

Once approved, CI/CD will build your MR and run the automated integration tests to make sure nothing breaks. Once merged, either directly or via an upstream release picked up by update_refs, CI/CD will build and deploy new prebuilt published build outputs.

Further Reading

Depending what you’re contributing to, you can follow the dedicated guide for each:

• GNOME OS: see the GNOME OS contribution guide
• GNOME Flatpak runtimes: see the Flatpak runtimes contribution guide
• GNOME OCI images: see the OCI images contribution guide

Contributing to GNOME OS

This guide covers the GNOME OS-specific parts of contributing. Read the contribution guide first for the general setup.

For automated integration tests, you also need to install the ssam_openqa tool manually like so:

cargo install --git https://gitlab.gnome.org/sthursfield/ssam_openqa.git

Or if you don’t have a rust toolchain already setup, you could use the precompiled the binaries:

curl -Lo ~/.local/bin/ssam_openqa "https://gitlab.gnome.org/api/v4/projects/sthursfield%2Fssam_openqa/packages/generic/$(uname -m)-unknown-linux-gnu/$(curl "https://gitlab.gnome.org/api/v4/projects/sthursfield%2Fssam_openqa/packages?package_name=$(uname -m)-unknown-linux-gnu&sort=desc" | jq -r '.[0].version')/ssam_openqa"
chmod +x ~/.local/bin/ssam_openqa

The TigerVNC viewer can be helpful in order to follow along as the automated integration tests are running. Field Monitor and Remote Viewer can not connect to the VNC server used for the automated integration tests.

1. Setting up secure boot keys

Before building images, you need to generate secure boot keys. For fast local development, you can use the snakeoil keys; these are the same keys CI/CD uses, which means that you can re-use the CI/CD caches for your local builds instead of rebuilding everything from source. Keep in mind however that these keys are publicly known and as a result provide zero security. To use them, run the following:

make -C files/boot-keys clean
make -C files/boot-keys IMPORT_MODE=snakeoil

If you want to deploy your local builds to your system, use the local import mode, which uses the snakeoil keys for the bootloader components but generates random keys for all other components by running the following:

make -C files/boot-keys clean
make -C files/boot-keys IMPORT_MODE=local

You can also generate completely fresh keys, which causes all components to be rebuilt by running the following:

make -C files/boot-keys clean
make -C files/boot-keys

For more information on the secure boot keys, see the secure boot keys guide.

2. Building and booting a GNOME OS image

If you’re already running GNOME OS (e.g. if you installed it by using the prebuilt images) and want to deploy your changes to it directly, you can skip this step and jump directly to the Rebuilding GNOME OS with your changes and deploying them section instead

2.1 Option 1: In a virtual machine

First, build and serve a local sysupdate repository in a separate terminal so the virtual machine can later enable the devel extension and others:

utils/run-sysupdate-repo.sh --devel # Append `--same-version` to avoid rebuilding the whole chain on the next run

Then, in another terminal, build and start a virtual machine with secure boot and a TPM by running the following; if you didn’t already generate the secure boot keys in Setting up secure boot keys, they will be generated automatically:

./utils/run-secure-vm.sh --gtk --debug-systemd --local-updates # Append `--rebuild-iso --reset-installed --reset-secure-state` to rebuild the image and completely reset the virtual machine, or drop `--gtk` to use a SPICE display (e.g. Field Monitor or Remote Viewer) instead

You can find more options with --help. The virtual machine image and state can be found at ./current-secure-vm/; the GTK display will open and allow you to interact with the virtual machine. The SSH command (and SPICE address, if enabled) to connect to the virtual machine will be printed to your console.

2.2 Option 2: On physical hardware

First, generate the secure boot keys as described in Setting up secure boot keys. Then build the ISO by running the following:

bst build gnomeos/live-image.bst
bst artifact checkout gnomeos/live-image.bst --directory ./iso

The ISO can be found at ./iso/disk.iso.

You can now write the ISO to a USB stick and boot from it on physical hardware, or manually boot from it in a virtual machine.

We also experimentally support some Android phones. Installation on those devices requires special steps and some things may not work, so please consult the linked documentation.

3. Installing your locally built GNOME OS image to disk

If you have secure boot enabled, systemd-boot will offer to auto-enroll the secure boot keys on the first boot.

After booting, you should install GNOME OS to disk by following the install section in the installation guide.

4. Rebuilding GNOME OS with your changes and deploying them

While it’s possible to rebuild the GNOME OS images on each change and reinstall them each time you make changes, this leads to a very slow iteration cycle and is not recommended. Instead, use the systemd-sysext and/or systemd-sysupdate workflows described in the following sections to build and deploy your changes to your local workstation, a remote machine, or a virtual machine in a much faster way.

The following uses $SSH_ARGS as placeholder SSH arguments when targeting a virtual machine or a remote machine. For a virtual machine started with ./utils/run-secure-vm.sh, use the arguments printed after running ./utils/run-secure-vm.sh (e.g. export SSH_ARGS="-i ssh/ephemeral -o IdentitiesOnly=yes root@vsock/777"). For a remote machine, set export SSH_ARGS="-tt user@remote-machine-hostname-or-ip".

4.1 Option 1: By building and installing a system extension (systemd-sysext)

This option works best if you want to temporarily and quickly deploy your changes to your local workstation, a remote machine, or a virtual machine. No reboot is required to see your changes in action. The one component that can’t be iterated on with system extensions is the kernel. For that, use the systemd-sysupdate option instead.

While this works for any of the included apps too, not just system components, iterating on apps directly using Flatpak via for example GNOME Builder or Foundry is preferred.

First, open a workspace for the component you want to work on as described in Making changes. Then, each time you want to build a system extension with your changes, run the following:

sysext-build-element --verbose zz-gnome-control-center core/gnome-control-center.bst

The system extension should now be available at ./zz-gnome-control-center.sysext.raw.

System extensions are applied alphabetically, so you want to prefix them (as we did above with zz-) in order to avoid being overwritten by other system extensions that will be loaded.

sysext-add --persistent zz-gnome-control-center.sysext.raw

run0 systemctl daemon-reload

sysext-remove zz-gnome-control-center

scp zz-gnome-control-center.sysext.raw $SSH_ARGS:/tmp/

scp -i ssh/ephemeral -o IdentitiesOnly=yes zz-gnome-control-center.sysext.raw youruser@vsock%777:/tmp

ssh -tt $SSH_ARGS sysext-add --persistent /tmp/zz-gnome-control-center.sysext.raw

ssh -tt $SSH_ARGS run0 systemctl daemon-reload

ssh -tt $SSH_ARGS sysext-remove zz-gnome-control-center

4.2 Option 2: By building, serving and updating from a local sysupdate repository (systemd-sysupdate)

This option works best if you want to permanently deploy your changes to your local workstation, a remote machine, or a virtual machine. A reboot is required to see your changes in action. Unlike with the systemd-sysext option, this option can be used to iterate on the kernel.

First, open a workspace for the component you want to work on as described in Making changes. Then, each time you want to build a systemd-sysupdate image with your changes and serve it from a local repository, run the following:

utils/run-sysupdate-repo.sh --devel # Append `--same-version` to avoid rebuilding the whole chain on the next run

In a second terminal, configure systemd-sysupdate to use the local repository and update to the images you’ve built.

run0 utils/enable-local-repo.sh --local
updatectl update host@l.1 # Without passing `--same-version` to run-sysupdate-repo.sh, the number after `l.` increments on each run
systemctl reboot

ssh $SSH_ARGS mkdir -p /tmp/gnome-build-meta
scp -r utils/ files/boot-keys/ $SSH_ARGS:/tmp/gnome-build-meta/

ssh $SSH_ARGS mkdir -p /tmp/gnome-build-meta
scp -i ssh/ephemeral -o IdentitiesOnly=yes -r utils/ files/boot-keys/ youruser@vsock%777:/tmp/gnome-build-meta

ssh -tt $SSH_ARGS run0 /tmp/gnome-build-meta/utils/enable-local-repo.sh --pubring /tmp/gnome-build-meta/boot-keys/import-pubring.pgp http://your-hostname-or-ip:8080

ssh -tt $SSH_ARGS run0 /tmp/gnome-build-meta/utils/enable-local-repo.sh --pubring /tmp/gnome-build-meta/boot-keys/import-pubring.pgp http://10.0.2.2:8080

ssh -tt $SSH_ARGS run0 updatectl update host@l.1 # Without passing `--same-version` to run-sysupdate-repo.sh, the number after `l.` increments on each run
ssh -tt $SSH_ARGS run0 systemctl reboot

To configure systemd-sysupdate to no longer use your local repository:

run0 utils/enable-local-repo.sh --clean

ssh -tt $SSH_ARGS run0 /tmp/gnome-build-meta/utils/enable-local-repo.sh --clean

5. Running automated integration tests

The automated integration tests, which also run in CI/CD, can be used to make sure that your changes didn’t break anything that already exists. To get started, fetch the test code and needles:

git clone https://gitlab.gnome.org/gnome/openqa-utils tests/openqa/utils
git clone https://gitlab.gnome.org/gnome/openqa-needles tests/openqa/needles

Then build the ISO as described in On physical hardware. The ISO is required because the tests run in a virtual machine. Once the ISO is ready, convert it to an image by running the following:

run0 ./utils/to-raw.sh ./iso/disk.iso ./iso/disk.img
run0 ./tests/openqa/utils/expand_disk.sh ./iso/disk.img 12 GB

Next, start the automated integration tests:

rm -rf ./iso/test-output
ssam_openqa run --hdd-path ./iso/disk.img --iso-path ./iso/disk.iso --tests-path ./tests/openqa --output-path ./iso/test-output

To debug tests interactively or follow along as they are running, press Ctrl+C, and enter t to get the TigerVNC command you can use to connect. You can then enter c to continue or a to abort. To connect with TigerVNC, run the following, replacing the example command below with the one printed after entering t:

flatpak run org.tigervnc.vncviewer localhost:43681 -Shared -ViewOnly

For more information on OpenQA, see End-to-end tests for GNOME OS.

6. Troubleshooting

For common troubleshooting steps, see the debugging guide.

7. Opening a merge request with your changes

See Opening a merge request with your changes.

Contributing to the GNOME Flatpak runtimes

This guide covers the Flatpak runtime-specific parts of contributing. Read the contribution guide first for the general setup.

1. Building and installing the runtimes locally

First, build the runtime, then check it out into a Flatpak repository:

bst build flatpak/runtimes-repo.bst
bst artifact checkout flatpak/runtimes-repo.bst --directory repo

Then add the repository as a remote to your system and install the runtime from there:

flatpak remote-add --user --no-gpg-verify testrepo repo
flatpak install testrepo org.gnome.Sdk org.gnome.Platform

The extensions (org.gnome.Sdk.Debug, org.gnome.Sdk.Docs, org.gnome.Platform.Locale, arch-compat layers, etc.) at flatpak/extensions-repo.bst can be built and installed by following the same pattern (see also the published build outputs).

To remove the runtime again, simply remove the remote:

flatpak remote-delete --user testrepo

2. Using the locally built runtimes

Run a shell in the SDK to poke at it directly:

flatpak run --user --command=bash org.gnome.Sdk//master

Or build an app of yours against the locally installed runtime using GNOME Builder or Foundry.

3. Opening a merge request with your changes

See Opening a merge request with your changes.

Contributing to the GNOME OCI images

This guide covers the OCI-image-specific parts of contributing. Read the contribution guide first for the general setup.

We provide OCI images that are as close as possible to the other formats we pack images into (Flatpak, DDIs). This is done because sometimes it’s easier to leverage existing OCI tooling for certain tasks. Unlike our other images, the OCI images are not “supported” in the same ways and only exist for testing and development. They are not meant to be used for any kind of deployment.

They are built and pushed to the container registry quay.io through the CI job deploy-oci.

The goals of the GNOME OCI images are:

• Make it possible to test parts of the stack with OCI tooling

  • e.g. sometimes it’s easier to run a GNOME OS container image rather than a whole VM
  • e.g. weird behavior in a library that shows up in the runtime, but it’s easier to test and debug the library with Toolbox rather than adding modules to the Flatpak manifest

• Make it possible to develop parts of the stack with the image

  • Develop a module against GNOME OS from any system that has an OCI runtime
  • Can be used as the CI image (directly or extended with ci-templates)

Deploying applications against the images is a non-goal. We have Flatpak and Flathub.

These OCI images are currently available (see also the published build outputs):

• Platform: Mirror of the org.gnome.Platform Flatpak runtime
• Sdk: Mirror of the org.gnome.Sdk Flatpak runtime
  • Includes the Docs extension
  • Includes the Debug extension (until we have debuginfod)
  • Toolbox-compatible
• GNOME OS: Mirror of the OS /usr tree
  • Includes locales
  • Toolbox-compatible
  • bootc-compatible
• GNOME OS Devel: The development system extension on top of the OS image
  • Includes locales
  • Includes docs
  • Includes debug symbols (until we have debuginfod)
  • Toolbox-compatible
  • bootc-compatible

1. Building the OCI images locally

First, build the elements:

bst build oci/platform/image.bst oci/sdk/image.bst oci/gnomeos/image.bst oci/gnomeos-devel/image.bst

Then import them into Podman:

bst artifact checkout --tar - oci/platform/image.bst | podman load
bst artifact checkout --tar - oci/sdk/image.bst | podman load
bst artifact checkout --tar - oci/gnomeos/image.bst | podman load
bst artifact checkout --tar - oci/gnomeos-devel/image.bst | podman load

2. Using the locally built OCI images with Toolbox/Distrobox

You can use the container images with Toolbox or Distrobox as an easy way to create containers.

To create a toolbox from an image:

toolbox create gnomeos-nightly -i quay.io/gnome_infrastructure/gnome-build-meta:gnomeos-devel-nightly
toolbox enter gnomeos-nightly

Note that Toolbox containers are updated using an update mechanism inside the container that will directly modify the container filesystem. GNOME OS does not have such a mechanism. When used in combination with Toolbox you will need to re-create the container if you want to update it and the toolchain it includes.

While some of the OCI images are compatible with bootc, it’s not a supported distribution channel. This is only for testing reasons and there are no plans of supporting a GNOME OS bootc image.

We think Discoverable Disk Images and systemd are a better fit for our use case and requirements. The only supported channel is and will remain the DDI images found in elements/gnomeos. More details on the subject can be found in this thread.

To generate and test a bootc image you will need the following:

./utils/generate-bootc-image.sh gnomeos /tmp
./utils/run-secure-vm.sh --image /tmp/bootable.img

See the GNOME OS contribution guide for more information on ./utils/run-secure-vm.sh.

3. Opening a merge request with your changes

See Opening a merge request with your changes.

OpenQA

GNOME OS is automatically tested on every commit. You can find the relevant documentation in our repository

TODO: pull them into our book

Secure Boot keys

This directory contains helpers to obtain a UEFI Secure Boot chain of trust for GNOME OS.

The Makefile has the following targets:

• generate-keys (default): obtain keys following IMPORT_MODE.
• clean: delete all generated files

There are various modes for obtaining keys, controlled by the IMPORT_MODE variable:

• unset (default): generate a full set of new keys locally.
• snakeoil: use pregenerated ‘snakeoil’ keys which are committed to the repo
• local: use ‘snakeoil’ for the root keys (PK, KEK and DB), generate the rest locally.
• import: read pregenerated keys from environment variables

See below for some guidance on which mode to use.

Use cases

UEFI Secure Boot ensures that a machine’s firmware will only boot operating systems and UEFI applications that are trusted by the machine owner.

It does this by embedding a chain of trust in the firmware, and requiring that UEFI applications are signed by a key that’s allowed by the chain of trust.

Most desktop and laptop vendors ship with a chain of trust controlled by Microsoft, and they enable Secure Boot by default in the firmware. This means that Microsoft Windows can start out-of-the-box on a modern machine. Any Linux distribution whose first-stage bootloader is signed by Microsoft can also start without any need to reconfigure firmware. That includes many mainstream Linux distributions today.

GNOME OS does not have any agreement with Microsoft to sign its bootloader. To boot GNOME OS on a modern laptop or desktop, you must be the machine owner and you’ll need to modify the Secure Boot configuration in the firmware to trust the keys.

If you downloaded an automated build from os.gnome.org, this is signed with keys stored in GNOME’s Gitlab. You don’t need to generate new keys in this case. You can go straight to adding the existing keys to the firmware’s chain of trust.

If you’re building GNOME OS locally, you will need to decide what signing keys to use. You have several options.

Snake Oil keys

The ‘snakeoil’ keys are pregenerated and committed to this Git repo.

That means, of course, that they don’t provide any security guarantee at all. (The name is reference to fake medicines that were common around the 19th century in Europe and the US.)

The gnome-build-meta CI uses the ‘snakeoil’ keys for building feature branches. That means the artifact cache contains prebuilt versions of the kernel, modules and bootloader, signed with the snakeoil key. Your local build might be faster using the ‘snakeoil’ keys as it can pull the prebuilt versions instead of locally building and signing new ones.

Local keys

By default make generates a full set of new keys.

This means your machine can be secure against certain attacks, like someone trying to boot a different operating system while you’re not watching to steal your data.

It also means you’ll need to locally build all the elements that are signed, such as the kernel and bootloader.

Local vendor keys

The IMPORT_MODE=local option is a hybrid of the first two options. It’s intended for local builds where you are deploying to a system that has an existing installation of GNOME OS, and you are deploying your local build as an update rather than installing from scratch.

In this mode, the insecure ‘snakeoil’ keys are used for the bootloader components. Those are not updated when you install GNOME OS as an update to an existing system, so you may as well take the fast path.

Everything else (kernel, modules, sysexts) gets a new locally generated key.

Outputs

The Makefile will output the following keys:

• PK: Platform Key
• KEK: Key Enrollment key
• DB: Signature Database
• VENDOR: Vendor key for signing UEFI applications
• MODULES: Vendor key for signing kernel modules
• SYSEXT: Vendor key for signing system extensions

It will additionally output -MIC variants of the first two keys. These are alternatives which include Microsoft keys in the chain of trust.

You can decide whether to enrol PK + KEK or PK-MIC + KEK-MIC in your machine firmware.

The former option ensures that the firmware will ONLY boot software signed with your chosen keys.

The latter option means the firmware will additionally allow any software allowed by the Microsoft keys. This is useful if you want to allow the machine to dual boot into other operating systems.

Further reading

There is lots of documentation online about UEFI Secure Boot for further reading. Here are some links:

• Arch Linux wiki: Unified Extensible Firmware Interface/Secure Boot
• Microsoft Windows Hardware Developer documentation: “Secure Boot overview”
• Proxmox wiki: Secure Boot Setup

Outputs

This document records the individual outputs of the gnome-build-meta project.

Key output Elements

Majority of the outputs of the gnome-build-meta project come directly from the outputs of individual BuildStream elements.

The table below summarises the key output elements for the gnome-build-meta project. It’s worth noting that every element produces some sort of output, that feed into these key elements.

See Contributing for details on how to use these elements.

Other Outputs

These outputs are produced outside of buildstream, by other scripts.

Published build outputs

This document records the published outputs of the gnome-build-meta project that go with different releases

For individual outputs that can be produced by the project at any time for development see Project outputs and Contributing

For details on releases see the GNOME release calendar and for branches see Contributing Branches

Nightly series of releases (master branch)

These are the outputs produced when merging to the master branch of gnome-build-meta for the nightly release series

Stable Series of releases (gnome-<version> stable branches)

These are the outputs produced when merging to any the stable branches of gnome-build-meta for stable release series

Stable Point Releases (Tags)

These are the outputs produced when a tag is added to the stable branches of gnome-build-meta for stable point releases

Other published output notes

The BuildStream cache server is populated on every build: https://gbm.gnome.org:11003 (configured in project.conf)

Images for the PinePhone, PinePhone Pro and Fairphone 5 are not automatically built by CI/CD, see Phones