[WIP] Add documentation for CI/CD setup and Commodore Compile Pipeline

docs/Makefile

@@ -16,7 +16,7 @@ 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
 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/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].
+
+[INFO]
+--
+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/compile-pipeline.adoc[CI/CD management]

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]