From 91947bb68e8184eba4c14476a6a14873f15e9ed4 Mon Sep 17 00:00:00 2001
From: Tom van Dijk <18gatenmaker6@gmail.com>
Date: Sun, 11 May 2025 15:08:59 +0200
Subject: [PATCH] nixos/forgejo: document migration version restrictions

---
 nixos/modules/services/misc/forgejo.md | 38 ++++++++++++++++++++++++++
 1 file changed, 38 insertions(+)

diff --git a/nixos/modules/services/misc/forgejo.md b/nixos/modules/services/misc/forgejo.md
index f234ebf44aef..cca557408639 100644
--- a/nixos/modules/services/misc/forgejo.md
+++ b/nixos/modules/services/misc/forgejo.md
@@ -24,6 +24,42 @@ Both modules and projects are likely to diverge further with each release.
 Which might lead to an even more involved migration.
 :::
 
+::: {.warning}
+The last supported version of Forgejo which supports migration from Gitea is
+*10.0.x*. You should *NOT* try to migrate from Gitea to Forgejo `11.x` or
+higher without first migrating to `10.0.x`.
+
+See [upstream migration guide](https://forgejo.org/docs/latest/admin/gitea-migration/)
+
+The last supported version of *Gitea* for this migration process is *1.22*. Do
+*NOT* try to directly migrate from Gitea *1.23* or higher, as it will likely
+result in data loss.
+
+See [upstream news article](https://forgejo.org/2024-12-gitea-compatibility/)
+:::
+
+In order to migrate, the version of Forgejo needs to be pinned to `10.0.x`
+*before* using the latest version. This means that nixpkgs commit
+[`3bb45b041e7147e2fd2daf689e26a1f970a55d65`](https://github.com/NixOS/nixpkgs/commit/3bb45b041e7147e2fd2daf689e26a1f970a55d65)
+or earlier should be used.
+
+To do this, temporarily add the following to your `configuration.nix`:
+
+```nix
+{ pkgs, ... }:
+let
+  nixpkgs-forgejo-10 = import (pkgs.fetchFromGitHub {
+    owner = "NixOS";
+    repo = "nixpkgs";
+    rev = "3bb45b041e7147e2fd2daf689e26a1f970a55d65";
+    hash = "sha256-8JL5NI9eUcGzzbR/ARkrG81WLwndoxqI650mA/4rUGI=";
+  }) {};
+in
+{
+  services.forgejo.package = nixpkgs-forgejo-10.forgejo;
+}
+```
+
 ### Full-Migration {#module-forgejo-migration-gitea-default}
 
 This will migrate the state directory (data), rename and chown the database and
@@ -49,6 +85,8 @@ chown -R forgejo:forgejo /var/lib/forgejo
 systemctl restart forgejo
 ```
 
+Afterwards, the Forgejo version can be set back to a newer desired version.
+
 ### Alternatively, keeping the gitea user {#module-forgejo-migration-gitea-impersonate}
 
 Alternatively, instead of renaming the database, copying the state folder and