298 lines
12 KiB
Markdown
298 lines
12 KiB
Markdown
# 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](https://invent.kde.org/sysadmin/ci-notary-service).
|
|
|
|
## 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](https://invent.kde.org/help/ci/variables/predefined_variables.md))
|
|
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](https://cdn.kde.org/ci-builds/).
|
|
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.
|
|
|
|
```yaml
|
|
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.
|
|
|
|
```yaml
|
|
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](https://community.kde.org/Sysadmin) 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](https://community.kde.org/Android/F-Droid#KDE_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](https://community.kde.org/Android/F-Droid#KDE_F-Droid_Release_Repository).
|
|
|
|
Example:
|
|
|
|
```yaml
|
|
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.
|
|
|
|
```yaml
|
|
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.
|
|
|
|
```yaml
|
|
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:
|
|
|
|
```yaml
|
|
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.
|
|
|
|
```yaml
|
|
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.
|
|
|
|
```yaml
|
|
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.
|
|
|
|
```yaml
|
|
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.
|
|
|
|
```yaml
|
|
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".
|