flatpak: Add guidance on using ci-flatdeb-builder

https://phabricator.apertis.org/T8509

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

---

This is in a draft state pending the actual ci-flatdeb-builder repository creation & the resulting filling of the TODOs in these changes, but other than that, this should be essentially ready. (Would like feedback here first, actually, on the configuration file format and such.)

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 that 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/>