12 KiB
Configuration of the KDE CI Notary Services
The *.ini files specify the general settings for the services and the corresponding
clients used by the KDE CI/CD pipelines. The *-projects.yaml files specify
the project-specific settings for the services.
For all projects that want to use some of the services, one or more branches
must be cleared for this service. This is done by adding the project and the
desired branches to the service's *-projects.yaml file.
The KDE CI Notary Services repository can be found here.
Project-specific Settings
The project-specific settings consist of two parts:
- Default settings shared by all projects (e.g. the signing key) and branches for which the service can be used by all projects;
- Settings that are specific for a project (or a project's branch) and that override the defaults. And branches for which the service can be used additionally to the default branches.
All settings can be specified globally for all projects (below defaults),
for all branches of one project (below the project's identifier), and
for one branch of one project (below the branch name in the project settings).
The top-level project identifier must match the path of the project
(CI_PROJECT_PATH)
on invent.kde.org, e.g. pim/itinerary.
Project-specific Settings for Common Services
buildpublisher
The project-specific settings are specified in buildpublisher-projects.yaml.
By default, no branches are published on KDE's CDN.
If you want to publish the AppImages, Windows installers, or macOS installers
built on the master branch and on the latest release branch then add the names of
those branches to the branches dictionary of the project's entry, e.g.
network/neochat:
branches:
master:
release/24.02:
Note that the branches below branches are specified as (empty) dictionaries.
Project-specific Settings for Android Services
For all projects, the application ID (e.g. org.kde.itinerary) must be specified
as applicationid below the project's entry. As a part of internal sanity check
the services verify that the application ID matches the ID of the APK, hence
applicationid must be specified regardless of whether the package is later
published by KDE services or not.
apksigner
The project-specific settings are specified in apksigner-projects.yaml. For
all projects, APKs built from the master branch are signed. If you also want to sign
the APKs built from the latest release branch, then add the name of this branch
to the branches dictionary of the project's entry, e.g.
pim/itinerary:
applicationid: org.kde.itinerary
branches:
release/23.08:
Note that the branch below branches is specified as (empty) dictionary.
Additionally, you will most likely have to specify the file name of the keystore which contains the key to sign your app and the file name of a file containing the password protecting the keystore. Google recommends to use separate signing keys for different apps. Submit a sysadmin ticket to get the keystore file on the system providing the signing service or to ask for a new key(store) to be created for you app.
fdroidpublisher
The project-specific settings are specified in fdroidpublisher-projects.yaml. For
all projects, APKs built from the master branch are published in KDE's F-Droid Nightly
Build repository.
If you also want to publish the APKs built from the latest release branch,
then add the name of this branch to the branches dictionary of the project's entry.
Additionally, you have to specify the stable-releases repository for this branch,
so that the stable builds of your app are published in KDE's F-Droid Release
repository.
Example:
pim/itinerary:
applicationid: org.kde.itinerary
branches:
release/23.08:
repository: stable-releases
googleplaypublisher
The project-specific settings are specified in googleplaypublisher-projects.yaml.
By default, no branches are published on Google Play. If you want to publish the APKs or the AAB
built from the latest release branch, then add the name of this branch to the branches
dictionary of the project's entry, e.g.
pim/itinerary:
applicationid: org.kde.itinerary
branches:
release/23.08:
With these settings, APKs (or an AAB) of Itinerary built from the release branch are published on Google Play.
All APKs or the AAB are published as draft in the app's beta track, i.e. after they were uploaded you have to release them manually via Google Play.
aabsigner
The project-specific settings are specified in aabsigner-projects.yaml. By default,
no AABs are signed. If you want to sign the AAB built from the latest release branch
with KDE's upload key specified in the default section, then add the name of this branch
to the branches dictionary of the project's entry, e.g.
utilities/ktrip:
applicationid: org.kde.ktrip
branches:
release/24.02:
Note that the branch below branches is specified as (empty) dictionary.
Signing an AAB is only necessary if you want to upload the AAB manually to Google Play.
Project-specific Settings for Linux Services
flatpaksigner
The project-specific settings are specified in flatpaksigner-projects.yaml. For
all projects the Flatpak bundle built from the master branch is signed (or, more
precisely, the Flatpak's commit to the repository is signed). By default, the
same signing key is used for all repositories.
For all projects the application ID (e.g. org.kde.itinerary) must be specified
as applicationid below the project's entry. The services verify that the
application ID matches the application ID of the Flatpak bundle. Additionally,
you have to specify the nightly repository for the Flatpak, and optionally its runtime repo (usually on flathub).
Example:
pim/itinerary:
applicationid: org.kde.itinerary
repository: itinerary-nightly
runtimerepourl: https://dl.flathub.org/repo/flathub.flatpakrepo
With these settings, Flatpak bundles of Itinerary built from the default branches (i.e. the master branch) are added to KDE's itinerary-nightly Flatpak repository.
A Note on KDE's Flatpak Repositories
As a general rule, each application should go in its own Flatpak repository. This may seem counter intuitive from a Flatpak perspective, but, for production stable releases, users should be retrieving those from Flathub rather than us, so these repositories are either staging repositories for production releases, or nightlies.
In either case, people likely only want to install a specific application or a small group of applications - not every single KDE project.
Only exception would be if there was a collection of closely coupled applications that should all be installed together - then those could go in the same repository.
If a Flatpak bundle is published for the first time and the target repository does not yet exist, then the repository is created by the service.
Project-specific Settings for Windows Services
windowsbinariessigner
The project-specific settings are specified in windowsbinariessigner-projects.yaml. By
default, no projects are cleared for signing Windows binaries (executable, DLLs,
NSIS installers) and Microsoft app packages (.msix or .appx).
If you want to sign Windows binaries packaged with Craft for a branch (or multiple
branches) of your project then add an entry for your project listing the branch
(or branches) in the branches dictionary of the project's entry, e.g.
utilities/kate:
applicationid: KDEe.V.Kate
branches:
master:
release/23.08:
With these settings, Windows binaries packaged with Craft for Kate are signed for GitLab jobs running on the master branch and the release/23.08 branch.
The application ID (e.g. KDEe.V.Kate) must be specified as applicationid
below the project's entry. It's the value of the Name attribute of the Identity
tag in the application's AppxManifest.xml file. For apps published in the
Microsoft Store it's also the official application identifier. The service
verifies that the application ID matches the ID of the APPX to sign.
applicationid only needs to be specified if the service is used for signing
APPX packages. If your project signs normal binaries only (.exe/.dll), then the
applicationid field can be omitted.
Note that the branches below branches are specified as (empty) dictionary.
microsoftstorepublisher
The project-specific settings are specified in microsoftstorepublisher-projects.yaml.
By default, no branches are published on Microsoft Store. If you want to submit the APPXs
built from the latest release branch, then add the name of this branch to the branches
dictionary of the project's entry, e.g.
network/neochat:
appstreamid: org.kde.neochat
keep:
- keywords
branches:
release/23.08:
With these settings, APPXs of NeoChat built from the release branch are submitted to Microsoft Store. The keywords currently used for NeoChat in Microsoft Store are kept while all other values are updated with NeoChat's AppStream data.
The AppStream ID of the app (e.g. org.kde.neochat) must be specified as
appstreamid below the project's entry. It is used to download the AppStream data
of the app from https://apps.kde.org/appdata/. Additionally, you can specify
that some information currently published on the Microsoft Store shall not
be overwritten with information retrieved from the AppStream data by listing
the corresponding attributes below keep. For details, see the documentation of
microsoftstorepublisher in the sysadmin/ci-notary-service> project.
Note that the branches below branches are specified as (empty) dictionary.
The APPXs are submitted to Microsoft Store but the submission is not committed, i.e. after they were uploaded you have to commit the submission manually in the Microsoft Store to publish your app.
Project-specific Settings for macOS Services
For all projects, the application ID (e.g. org.kde.Kate) must be specified
as applicationid below the project's entry. As a part of internal sanity check
the services verify that the application ID matches the value of CFBundleIdentifier
in the applications Info.plist. Typically, CMake sets CFBundleIdentifier via the
MACOSX_BUNDLE_GUI_IDENTIFIER target property.
macappsigner
The project-specific settings are specified in macappsigner-projects.yaml. For
all projects, macOS APP bundles and DMGs built with Craft from the master branch
are signed. If you also want to sign the bundles built from the latest release branch,
then add the name of this branch to the branches dictionary of the project's entry, e.g.
utilities/kate:
applicationid: org.kde.Kate
branches:
release/24.08:
Note that the branch below branches is specified as (empty) dictionary.
Without signing, Apple will force the app to crash on startup.
macappnotarizer
The project-specific settings are specified in macappnotarizer-projects.yaml. By
default, no branches are enabled for notarization of macOS apps. If you want to
notarize macOS DMGs packaged with Craft for a branch (or multiple branches) of your
project then add an entry for your project listing the branch (or branches) in the
branches dictionary of the project's entry, e.g.
utilities/kate:
applicationid: org.kde.Kate
branches:
release/24.08:
Note that the branch below branches is specified as (empty) dictionary.
Please also note that, since notarization is done via API requests to Apple servers,
we don't want high traffic branches like master to be enabled for notarization.
Notarization is optional for macOS apps. Even though it is a bit more complicated you can run apps with signing only. Notarization will make it easier to run apps on macOS and prevents scary messages like "This app is not verified".