flatpak: Add guidance on using ci-flatdeb-builder

https://phabricator.apertis.org/T8509



Signed-off-by: Ryan Gonzalez <ryan.gonzalez@collabora.com>

content/guides/flatpak.md

@@ -915,6 +915,248 @@ flatpak install --sign-verify=ed25519=inline:B3a86SmB+sby/N5onaxTXjK1OEAbZOI2fsd
 This option works the same way with both `flatpak build-import-bundle` and
  `flatpak install` commands.
 
+# Building Flatpaks on GitLab CI
+
+[ci-flatdeb-builder](https://gitlab.apertis.org/infrastructure/ci-flatdeb-builder/)
+provides a premade GitLab CI pipeline generator streamlines the process of
+building, testing, and publishing Flatpak runtimes and apps located on GitLab.
+
+## Initial Setup
+
+In order to use ci-flatdeb-builder, the target repository's [the repository's
+"CI/CD configuration
+file"](https://docs.gitlab.com/ee/ci/pipelines/settings.html#specify-a-custom-cicd-configuration-file)
+should to be set to point to `REPO_URL/-/raw/main/ci-flatdeb-builder.yaml`,
+where `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
+variables](https://docs.gitlab.com/ee/ci/variables/#add-a-cicd-variable-to-a-project)
+should be set on the repository:
+
+- `ARCHIVE_SECRET_FILE` should be a
+  [**file**](https://docs.gitlab.com/ee/ci/variables/#cicd-variable-types)
+  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_PUBLIC_KEY` and `FLATPAK_PRIVATE_KEY` should 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.
+
+In addition, instead of being set per-repository, these values can be set on a
+GitLab [group](https://docs.gitlab.com/ee/user/group/), which will result in
+ci-flatdeb-builder being run on all the individual repositories within.
+
+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:
+
+- `UPLOAD_HOST`: The SSH server where build results should be published to (i.e.
+  the server that `ARCHIVE_SECRET_FILE` is used to access).
+- `UPLOAD_ROOT_MAIN`, `UPLOAD_ROOT_TEST`: The paths on `UPLOAD_HOST` where the
+  resulting Flatpak repositories will be placed for stable and test builds,
+  respectively.
+- `REMOTE_URL_MAIN`, `REMOTE_URL_TEST`: The URLs where build results will be
+  accessible at after being uploaded to `UPLOAD_HOST`.
+- `CI_FLATDEB_BUILDER_REPO`: The URL of the GitLab repository containing
+  `ci-flatdeb-builder.yaml`; i.e., the `REPO_URL` that 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 `main` in 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.
+
+## Source Layout
+
+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 `apps/`.
+- Otherwise, any `*.yaml` files in the root directory will be built via
+  flatpak-builder.
+
+## Configuration
+
+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
+named `flatdeb-builder.yaml` in the repository root. A sample configuration file
+is below:
+
+```yaml
+stable_branches: main_only
+install_deps_from:
+  url: https://images.apertis.org/flatpak/repo/apertis.flatpakrepo
+supported_architectures:
+  - aarch64
+  - arm
+  - x86_64
+tests:
+  group1:
+    targets:
+      runtimes:
+        - org.apertis.runtime1
+        - org.apertis.runtime2
+      apps:
+        - org.apertis.app1
+        - org.apertis.app2
+    command: ./run-tests-1.sh
+  group2:
+    targets:
+      apps:
+        - org.apertis.app3
+        - org.apertis.app4
+    command: ./run-tests-2.sh
+flatpakrepo:
+  name: sample
+  template: |
+    [Flatpak Repo]
+    Title=Sample Repository
+    Url=$REMOTE_URL
+    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=$FLATPAK_PUBLIC_KEY
+```
+
+### Stable Branch Naming
+
+```yaml
+stable_branches: main_only  # or 'versioned'
+```
+
+This determines the naming scheme for the repository's stable branches:
+
+- `main_only` (the default): the `main` or `master` branch is the Git
+  repository's stable branch. Built Flatpaks will have the version `stable` when
+  built from the stable branch or `test` when 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 `v2022`.
+
+  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/v2022` is forked to as
+  `wip/user/fix-things`, v2022 will be used.
+
+Generally, `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.
+
+### Installing Dependencies
+
+```yaml
+install_deps_from:
+  url: https://images.apertis.org/flatpak/repo/apertis.flatpakrepo
+  sign: ed25519  # or 'gpg', 'none'
+```
+
+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.
+- `gpg` is 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 `none`.)
+- `none` will treat the remote as being unsigned.
+
+### Limiting Supported Architectures
+
+```yaml
+supported_architectures:
+  - aarch64
+  - arm
+  - x86_64
+```
+
+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:
+
+```yaml
+supported_architectures:
+  - aarch64
+  - x86_64
+```
+
+### Defining Tests
+
+```yaml
+tests:
+  group1:
+    targets:
+      runtimes:
+        - org.apertis.runtime1
+        - org.apertis.runtime2
+      apps:
+        - org.apertis.app1
+        - org.apertis.app2
+    command: ./run-tests-1.sh
+  group2:
+    targets:
+      apps:
+        - org.apertis.app3
+        - org.apertis.app4
+    command: ./run-tests-2.sh
+```
+
+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,
+consisting of:
+
+- `targets`: This lists Flatpak runtimes (under the `runtimes` key) and
+  applications (under the `apps` key) 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 `targets`.
+
+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
+  {{< ref "#stable-branch-naming" >}} for more information on what this is).
+- `$FLATPAK_ARCH`: The architecture the Flatpaks are built for (one of `x86_64`,
+  `arm`, `aarch64`).
+- `$DEBIAN_ARCH`: The Debian-compatible architecture name corresponding to
+  `$FLATPAK_ARCH` (one of `amd64`, `arm64`, `armhf`).
+- `$TARGETS_REPO`: Path to an OSTree repository containing the runtimes and
+  apps in `targets`.
+
+### Publishing a .flatpakrepo
+
+```yaml
+flatpakrepo:
+  name: sample
+  template: |
+    [Flatpak Repo]
+    Title=Sample Repository
+    Url=$REMOTE_URL
+    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=$FLATPAK_PUBLIC_KEY
+```
+
+This will automatically use the given `template` to create `name.flatpakrepo` in
+the published OSTree repository directory. The template can reference two
+different variables that will be substituted inside:
+
+- `$REMOTE_URL` is the URL to the OSTree repository.
+- `$FLATPAK_PUBLIC_KEY` is the public key that the repository is signed with.
+  (If the repository is unsigned, this will be empty.)
+
 # References
 
 Flatpak reference documentation: <https://docs.flatpak.org/>