Flatpak GitHub Actions
August 25, 2026 ยท View on GitHub
How to use
Building stage
Add a new workflow by creating a .yml file under .github/workflows with this content
on:
push:
branches: [main]
pull_request:
name: CI
jobs:
flatpak:
name: "Flatpak"
runs-on: ubuntu-latest
container:
image: ghcr.io/flathub-infra/flatpak-github-actions:gnome-48
options: --privileged
steps:
- uses: actions/checkout@v4
- uses: flatpak/flatpak-github-actions/flatpak-builder@v6
with:
bundle: palette.flatpak
manifest-path: org.gnome.zbrown.Palette.yml
Inputs
| Name | Description | Required | Default |
|---|---|---|---|
manifest-path | The relative path of the manifest file | Required | - |
stop-at-module | Stop at the specified module, ignoring it and all the following ones. Using this option disables generating bundles. | Optional | Build all modules from the manifest file |
bundle | The bundle name | Optional | app.flatpak |
build-bundle | Whether to build a bundle or not | Optional | true |
build-debug-bundle | Whether to build a debug bundle or not | Optional | false |
repository-name | The repository name, used to fetch the runtime when the user download the Flatpak bundle or when building the application | Optional | flathub |
repository-url | The repository url, used to fetch the runtime when the user download the Flatpak bundle or when building the application | Optional | https://flathub.org/repo/flathub.flatpakrepo |
run-tests | Enable/Disable running tests. This overrides the flatpak-builder option of the same name, which invokes make check or ninja test. Network and X11 access is enabled, with a display server provided by xvfb-run. | Optional | false |
branch | The default flatpak branch | Optional | master |
cache | Enable/Disable caching .flatpak-builder directory | Optional | true |
restore-cache | Enable/Disable cache restoring. If caching is enabled. | Optional | true |
save-cache | Enable/Disable cache uploading. If caching is enabled. | Optional | true |
cache-key | Specifies the cache key. CPU arch is automatically added, so there is no need to add it to the cache key. | Optional | flatpak-builder-${arch}-${sha256(manifestPath)} |
arch | Specifies the CPU architecture to build for | Optional | x86_64 |
mirror-screenshots-url | Specifies the URL to mirror screenshots | Optional | - |
gpg-sign | The key to sign the package | Optional | - |
build-dir | The directory to build the application in. | Optional | flatpak_app |
repo-dir | The directory of the flatpak repository. | Optional | repo |
state-dir | The directory to store the build state/cache in. | Optional | .flatpak-builder |
keep-build-dirs | Keep build directories after the build finishes (passes --keep-build-dirs to flatpak-builder). Useful for debugging intermediate files. | Optional | false |
verbose | Enable verbosity | Optional | false |
upload-artifact | Whether to upload the resulting bundle or not as an artifact | Optional | true |
artifact-name | Name of the uploaded artifact | Optional | app-${arch}.flatpak |
Note: repo-dir and state-dir must be under the same partition.
Building for multiple CPU architectures
To build for CPU architectures other than x86_64, the GitHub Actions workflow has to either natively be running on that architecture (e.g. on an aarch64 self-hosted GitHub Actions runner), or the container used must be configured to emulate the requested architecture (e.g. with QEMU).
For example, to build a Flatpak for both x86_64 and aarch64 using emulation, use the following workflow as a guide:
on:
push:
branches: [main]
pull_request:
name: CI
jobs:
flatpak:
name: "Flatpak"
runs-on: ubuntu-latest
container:
image: ghcr.io/flathub-infra/flatpak-github-actions:gnome-48
options: --privileged
strategy:
matrix:
arch: [x86_64, aarch64]
# Don't fail the whole workflow if one architecture fails
fail-fast: false
steps:
- uses: actions/checkout@v4
# Docker is required by the docker/setup-qemu-action which enables emulation
- name: Install deps
if: ${{ matrix.arch != 'x86_64' }}
run: |
# Use the static binaries because it's unable to use a package manager
curl https://download.docker.com/linux/static/stable/x86_64/docker-26.0.0.tgz --output ./docker.tgz
tar xzvf docker.tgz
mv docker/* /usr/bin
- name: Set up QEMU
if: ${{ matrix.arch != 'x86_64' }}
id: qemu
uses: docker/setup-qemu-action@v3
with:
platforms: arm64
- uses: flatpak/flatpak-github-actions/flatpak-builder@v6
with:
bundle: palette.flatpak
manifest-path: org.gnome.zbrown.Palette.yml
arch: ${{ matrix.arch }}
Multi arch build using public ARM64 runners
Since, January 2025, GitHub offers public ARM64 runners. So a multi-arch build can be performed using that.
name: CI
on:
push:
branches: [main]
pull_request:
jobs:
flatpak:
name: "Flatpak"
container:
image: ghcr.io/flathub-infra/flatpak-github-actions:gnome-48
options: --privileged
strategy:
matrix:
variant:
- arch: x86_64
runner: ubuntu-24.04
- arch: aarch64
runner: ubuntu-24.04-arm
runs-on: ${{ matrix.variant.runner }}
steps:
- uses: actions/checkout@<commit hash>
- uses: flatpak/flatpak-github-actions/flatpak-builder@v6
with:
bundle: palette.flatpak
manifest-path: org.gnome.zbrown.Palette.yml
arch: ${{ matrix.variant.arch }}
verbose: true
Building for Automated Tests
As described in the Inputs documentation, specifying run-tests: true will amend the Flatpak manifest to enable Network and X11 access automatically. Any other changes to the manifest must be made manually, such as building the tests (e.g. -Dtests=true) or any other options (e.g. --buildtype=debugoptimized).
Most developers will want to run tests on pull requests, before merging into the main branch of a repository. To ensure your manifest is building the correct code, you should set the sources entry for your project to "type": "dir" with the path key relative to the manifest's location in the repository.
In the example below, the manifest is located at /build-aux/flatpak/org.gnome.zbrown.Palette.json, so the path key is set to ../../. If the manifest were in the project root instead, the correct usage would be "path": "./".
{
"app-id" : "org.gnome.zbrown.Palette",
"runtime" : "org.gnome.Platform",
"runtime-version" : "master",
"sdk" : "org.gnome.Sdk",
"command" : "org.gnome.zbrown.Palette",
"finish-args" : [
"--share=ipc",
"--device=dri",
"--socket=fallback-x11",
"--socket=wayland"
],
"modules" : [
{
"name" : "palette",
"buildsystem" : "meson",
"config-opts" : [
"--prefix=/app",
"--buildtype=debugoptimized",
"-Dtests=true"
],
"sources" : [
{
"name" : "palette",
"buildsystem" : "meson",
"type" : "dir",
"path" : "../../"
}
]
}
]
}
Deployment stage
If you want to deploy the successfully built Flatpak application to a remote repository
on:
push:
branches: [main]
name: Deploy
jobs:
flatpak:
name: "Flatpak"
runs-on: ubuntu-latest
container:
image: ghcr.io/flathub-infra/flatpak-github-actions:gnome-48
options: --privileged
steps:
- uses: actions/checkout@v4
- uses: flatpak/flatpak-github-actions/flatpak-builder@v6
name: "Build"
with:
bundle: palette.flatpak
manifest-path: org.gnome.zbrown.Palette.yml
- uses: flatpak/flatpak-github-actions/flat-manager@v6
name: "Deploy"
with:
repository: elementary
flat-manager-url: https://flatpak-api.elementary.io
token: some_very_hidden_token
end-of-life: "The application has been renamed to..."
end-of-life-rebase: "org.zbrown.Palette"
Inputs
| Name | Description | Required | Default |
|---|---|---|---|
repository | The repository to push the build into | Required | - |
flat-manager-url | The flat-manager remote URL | Required | - |
token | A flat-manager token | Required | - |
end-of-life | Reason for end of life | Optional | - |
end-of-life-rebase | The new app-id | Optional | - |
build-log-url | URL to Flatpak build log | Optional | - |
verbose | Enable verbosity | Optional | false |
Container Images
You can use the generated images by Flathub at https://github.com/flathub-infra/actions-images to avoid re-installing the SDKs for every build.