Add documentation for CI/CD setup and Commodore Compile Pipeline

docs/Makefile

@@ -13,10 +13,10 @@ asciidoctor_epub3_cmd  ?= $(docker_cmd) run $(docker_opts) --volume "$${PWD}":/d
 asciidoctor_opts ?= --destination-dir=$(out_dir)
 asciidoctor_kindle_opts ?= --attribute ebook-format=kf8
 
-vale_cmd ?= $(docker_cmd) run $(docker_opts) --volume "$${PWD}"/src/modules/ROOT/pages:/pages vshn/vale:2.6.1 --minAlertLevel=error /pages
+vale_cmd ?= $(docker_cmd) run $(docker_opts) --volume "$${PWD}"/src/modules/ROOT/pages:/pages ghcr.io/vshn/vale:2.27.0 --minAlertLevel=error /pages
 hunspell_cmd ?= $(docker_cmd) run $(docker_opts) --volume "$${PWD}":/spell vshn/hunspell:1.7.0 -d en,vshn -l -H _public/**/**/*.html
 htmltest_cmd ?= $(docker_cmd) run $(docker_opts) --volume "$${PWD}"/_public:/test wjdp/htmltest:v0.12.0
-preview_img ?= vshn/antora-preview:3.0.1.1
+preview_img ?= ghcr.io/vshn/antora-preview:3.1.2.3
 preview_cmd ?= $(docker_cmd) run --rm --publish 35729:35729 --publish 2020:2020 --volume "${PWD}":/preview/antora $(preview_img) --antora=docs --style=syn
 
 .PHONY: docs-all

docs/modules/ROOT/pages/explanations/cicd-support.adoc

@@ -0,0 +1,40 @@
+= CI/CD Support
+
+Lieutenant can configure Git repositories to enable CI/CD for tenant repositories.
+This feature is designed to support the https://github.com/projectsyn/commodore-compile-pipelines[Commodore Compile Pipeline], but can be used independently.
+
+
+[NOTE]
+--
+Automatic configuration of CI/CD tooling is so far only supported on GitLab.
+
+To allow the Lieutenant Operator to connect to GitLab, refer to xref:how-tos/gitlab-connection.adoc[Connection to GitLab].
+--
+
+== CI/CD pipeline configuration
+Lieutenant configures the CI/CD pipeline by managing files in the tenant repository, such as the `.gitlab-ci.yml` file.
+These files are configured in the tenant's `spec.compilePipeline.pipelineFiles`, where arbitrary files can be defined that are added to the tenant repository if the compile pipeline is enabled.
+
+The system assumes that the CI/CD system (for example GitLab CI) can be fully configured using files in the repository.
+
+== CI/CD parameters
+Lieutenant ensures that the CI/CD pipeline can access the Lieutenant API as well as the necessary cluster catalog repositories.
+This is achieved by passing a number of parameters to the CI/CD pipeline.
+
+The mechanism by which these parameters are provided is specific to a Git host.
+Currently, only GitLab is supported, where this information is provided through CI/CD variables on the tenant repository.
+
+
+In particular, the following parameters are provided on a tenant where `spec.compilePipeline.enabled` is set to `true`:
+
+* `ACCESS_TOKEN_CLUSTERNAME`, where `CLUSTERNAME` is the name of a specific cluster, with `-` replaced by `_`.
+  This contains an access token, which has read-write access the corresponding cluster's catalog repository.
+  The access token is created automatically for each cluster where `spec.enableCompilePipeline` is set to `true` and `spec.gitRepoTemplate.accessToken` contains a valid secret reference.
+* `COMMODORE_API_URL`. This contains the URL at which the Lieutenant API can be accessed.
+* `COMMODORE_API_TOKEN`. This contains an access token for the Lieutenant API.
+* `CLUSTERS`. This contains a space-separated list of cluster IDs for which the CI/CD pipeline should run; that is, the list of clusters where `spec.enableCompilePipeline` is `true`.
+
+The CI/CD pipeline can use these parameters to compile cluster catalogs with Commodore, and push them to the corresponding catalog repositories.
+The https://github.com/projectsyn/commodore-compile-pipelines[Commodore Compile Pipeline] is a GitLab CI pipeline definition which accomplishes that.
+However, it is possible to use other CI/CD systems.
+

docs/modules/ROOT/pages/how-tos/compile-pipeline-setup.adoc

@@ -0,0 +1,92 @@
+= Compile Pipeline Setup
+
+Lieutenant can automatically configure CI/CD tooling on your Git repositories.
+This page explains how to set up the https://github.com/projectsyn/commodore-compile-pipelines[Commodore Compile Pipeline].
+
+[NOTE]
+--
+Automatic configuration of CI/CD tooling is so far only supported on GitLab.
+
+To allow the Lieutenant Operator to connect to GitLab, refer to xref:how-tos/gitlab-connection.adoc[Connection to GitLab].
+--
+
+== Enabling the Compile Pipeline for individual tenants and clusters
+
+The `compilePipelineSpec` field on a Tenant object governs how CI/CD tooling is managed.
+To enable the Commodore Compile Pipeline on a tenant, configure it as follows:
+
+[source,bash]
+....
+kubectl patch tenant my-tenant --type merge -p '
+spec:
+  compilePipeline:
+    enabled: true <1>
+    pipelineFiles:
+      .gitlab-ci.yml: | <2>
+        include:
+          - https://raw.githubusercontent.com/projectsyn/commodore-compile-pipelines/main/gitlab/commodore-pipeline.yml
+'
+....
+<1> This field enables the compile pipeline for this tenant.
+If it is `false` or unset, no CI/CD tooling will be managed, regardless of other configuration options on the tenant or its clusters.
+<2> This example causes Lieutenant to create a file `.gitlab-ci.yml` in the tenant repository, which references the open-source https://github.com/projectsyn/commodore-compile-pipelines[Commodore Compile Pipeline].
+It is possible to customize this file, or create different files.
+
+In addition, the Compile Pipeline must be enabled for each cluster where CI/CD is desired:
+[source,bash]
+....
+kubectl patch cluster my-cluster --type merge -p '
+spec:
+  enableCompilePipeline: true <1>
+  gitRepoTemplate:
+    accessToken:
+      secretRef: my-cluster-api-token <2>
+'
+....
+<1> This field enables the compile pipeline for this cluster.
+If it is `false` or unset, the tenant's CI/CD configuration will disregard this cluster.
+<2> For the compile pipeline to work, an access token for the Git repository is required.
+Lieutenant creates this access token and will store it in the secret specified here.
+
+
+== Enabling the Compile Pipeline for all clusters of a tenant
+
+We can leverage templating to configure and enable the Compile Pipeline for all clusters on a tenant.
+For more information on templating, refer to xref:explanations/templating.adoc[Templating].
+
+The following example configures a tenant such that its clusters automatically include the correct configuration for the Compile Pipeline:
+[source,bash]
+....
+kubectl patch tenant my-tenant --type merge -p '
+spec:
+  clusterTemplate:
+    enableCompilePipeline: true
+    gitRepoTemplate:
+      accessToken:
+        secretRef: '{{ .Name }}-api-token'
+'
+....
+
+
+== Enabling the Compile Pipeline for all tenants
+
+We can leverage tenant templating to configure and enable the Compile Pipeline for all clusters on a tenant.
+For more information on templating, refer to xref:how-tos/create-tenant.adoc#_tenant_templating[Tenant Templating].
+
+[source,bash]
+....
+kubectl patch tenanttemplate my-template --type merge -p '
+spec:
+  clusterTemplate:
+    enableCompilePipeline: true
+    gitRepoTemplate:
+      accessToken:
+        secretRef: '{{ .Name }}-api-token'
+  compilePipeline:
+    enabled: true
+    pipelineFiles:
+      .gitlab-ci.yml: |
+        include:
+          - https://raw.githubusercontent.com/projectsyn/commodore-compile-pipelines/main/gitlab/commodore-pipeline.yml
+'
+....

docs/modules/ROOT/partials/nav-explanation.adoc

@@ -2,3 +2,4 @@
 * xref:lieutenant-operator:ROOT:explanations/deletion.adoc[Object Deletion]
 * xref:lieutenant-operator:ROOT:explanations/templating.adoc[Templating]
 * xref:lieutenant-operator:ROOT:explanations/rbac-access.adoc[Multi tenant access]
+* xref:lieutenant-operator:ROOT:explanations/cicd-support.adoc[CI/CD support]

docs/modules/ROOT/partials/nav-howtos.adoc

@@ -2,6 +2,7 @@
 * xref:lieutenant-operator:ROOT:how-tos/vault.adoc[Vault Configuration]
 * xref:lieutenant-operator:ROOT:how-tos/local-env.adoc[Running Operator locally]
 * xref:lieutenant-operator:ROOT:how-tos/gitlab-connection.adoc[GitLab Connection]
+* xref:lieutenant-operator:ROOT:how-tos/compile-pipeline-setup.adoc[Set up the Commodore Compile Pipeline]
 * xref:lieutenant-operator:ROOT:how-tos/create-tenant.adoc[Create a Tenant]
 * xref:lieutenant-operator:ROOT:how-tos/create-cluster.adoc[Create a Cluster]
 * xref:lieutenant-operator:ROOT:how-tos/create-gitrepo.adoc[Create a Git Repository]