Document GitLab CI configuration

.gitlab-ci.yml

@@ -1,8 +1,52 @@
+# Automatic NixOS upgrades (modules/server/system.nix) requires updating
+# flake.lock in the repository periodically. This repository is hosted on
+# Gitea, which doesn't have good support for CI. Instead, the repository is
+# mirrored to GitLab.com, where the following is configured to run on a
+# schedule. The GitLab repository is then mirrored back to Gitea:
+#
+#                      ┌──────────┐
+#                      │ Schedule │
+#                      └────┬─────┘
+#                         Update
+#                       flake.lock
+#                           │
+# ┌─────────┐  Mirror  ┌────▼─────┐
+# │  Gitea  │◄────────►│  GitLab  │
+# └─────────┘          └──────────┘
+#
+# GitLab:
+#   Settings:
+#     Access Tokens:
+#       - "Push Token": read_repository,write_repository, Maintainer
+#     Repository:
+#       Mirroring repositories:
+#          - ssh://git@git.caspervk.net:2222/caspervk/nixos.git, SSH public key authentication
+#     CI/CD:
+#       Variables:
+#         ACCESS_TOKEN: <Push Token>, Protect, Mask
+#   Build:
+#     Pipeline schedules:
+#       - Update flake.nix
+#         23 17 * * MON
+#
+# Gitea:
+#   Settings:
+#     Repository:
+#       Mirror Settings:
+#         - URL: <GitLab repo HTTP URL>
+#           Authorization:
+#             Username: oauth2
+#             Password: <Push Token>
+#             Sync when commits are pushed: Yes
+#     Deploy Keys:
+#       - <"Copy SSH public key" from GitLab>Settings>Repository>Mirroring repositories>
+#         Enable Write Access: Yes
+
 workflow:
   rules:
     - if: '$CI_PIPELINE_SOURCE == "schedule"'
 
-Update Flake.nix:
+Update flake.nix:
   image: nixos/nix:latest
   script:
     - git config user.email "snowflake@caspervk.net"