Как перенести данные из Gitea в Forgejo, не сломав репозитории

Вы останавливаете Gitea, устанавливаете Forgejo, копируете app.ini и каталог данных и запускаете сервис так, как описано в каждом руководстве по миграции. Веб-интерфейс поднимается. Затем миграция базы данных завершается ошибкой, или, что хуже, Forgejo отказывается запускаться, потому что версия вашей схемы слишком новая для его понимания. Вы находитесь на Gitea 1.23 или новее, и простое обновление на месте, которое описывают все, больше к вам не применимо.

Forgejo стал полноценным форком Gitea в начале 2024 года, и с тех пор оба проекта разошлись на уровне схемы базы данных. То, как вы будете переносить Gitea в Forgejo, теперь полностью зависит от вашей версии Gitea. Это руководство даёт точный путь для вашей версии, полные команды как для нативной установки, так и для Docker, обходные пути для Gitea 1.23+ и чек-лист проверки, чтобы вы перенеслись без потери репозиториев, issues или пользователей.

Кратко (TL;DR)

• Версионный обрыв реален. Forgejo v10.0 была последним релизом, поддерживающим прозрачное прямое обновление с Gitea. Gitea v1.22 — самая новая версия, для которой доступен поддерживаемый прямой путь.
• На Gitea v1.22 или более ранней версии: сначала перейдите на Forgejo v10.0.x, затем обновите Forgejo v10 до текущего релиза (v15). Два шага, оба поддерживаются.
• На Gitea v1.23 или новее: официально поддерживаемого прямого пути не существует. Вы выбираете между понижением версии SQL/схемы, скриптами миграции от сообщества, миграцией через репозиторий/API или поэтапной миграцией на новый сервер с использованием одного из этих методов. Каждый вариант несёт свой компромисс по потере данных.
• Сделайте резервную копию каталога данных и базы данных, прежде чем что-либо трогать. Каждый путь ниже предполагает, что у вас есть восстанавливаемая резервная копия. Неподдерживаемые пути предполагают это вдвойне.
• Некоторые вещи всегда требуют внимания после миграции: запланируйте пересоздание или аудит Personal Access Tokens, перерегистрацию раннеров Actions, а также удаление и пересборку поискового индекса Bleve. Учитывайте это независимо от выбранного пути.
• Миграция не обязательна. Gitea активно поддерживается. Решение "остаться на Gitea" оправдано, если риск миграции перевешивает выгоду в вашей ситуации.

Вне рамок этой статьи: миграция с Gogs, GitHub или GitLab на Forgejo, а также настройка Forgejo Actions с нуля.

Предварительные требования / что вам понадобится

Прежде чем выполнять хотя бы одну команду, убедитесь, что у вас есть полная, восстанавливаемая резервная копия двух вещей: каталога данных Gitea (/var/lib/gitea при стандартной нативной установке) и базы данных. Если ваша база данных — SQLite, этот файл находится внутри каталога данных; если это PostgreSQL или MySQL, сделайте отдельный дамп с помощью pg_dump или mysqldump. Миграция без проверенной резервной копии — это не миграция, а азартная игра.

Вам также понадобится:

• Ваша текущая версия Gitea. Запустите gitea --version (или docker exec <container> gitea --version. Именно это число определяет весь ваш путь.
• Тип вашей базы данных: SQLite, PostgreSQL или MySQL. Некоторые обходные пути специфичны для конкретной базы данных.
• Root-доступ или sudo на сервере.
• Понимание того, что поддерживаемый путь устанавливает Forgejo v10.0 как промежуточный шаг. Forgejo v10.0 находится в статусе EOL с 16 апреля 2025 года. Вы устанавливаете её только на время миграции и сразу же обновляетесь с неё.

Почему сломался путь прямого обновления

В декабре 2024 года проект Forgejo опубликовал заявление о совместимости провела жёсткую черту: «Будущие версии Forgejo не будут поддерживать обновление с экземпляров Gitea версии v1.23 и выше». Это предложение — вся проблема в одной строке.

Когда Forgejo отделилась от Gitea в начале 2024 года, две кодовые базы продолжили расходиться, а схемы баз данных стали отличаться друг от друга. Forgejo поддерживала окно совместимости, чтобы существующие операторы Gitea могли перейти, но у этого окна был конец. Forgejo v10.0, выпущенная 16 января 2025 года, была "the last version to allow a transparent upgrade from Gitea v1.22 or lower." Любая версия новее v10.0 не сможет напрямую прочитать базу данных Gitea.

Именно момент времени и застаёт людей врасплох. Gitea v1.23 вышла в конце 2024 года, и текущий релиз Gitea по состоянию на июнь 2026 года — v1.26.4. Если вы поддерживали свой экземпляр Gitea более-менее актуальным, вы уже прошли этот рубеж, и стандартные руководства больше не описывают вашу ситуацию.

Вывод раздела: поддерживаемый прямой путь ограничен версией Gitea v1.22. Всё, что новее, требует дополнительного шага.

Найдите свой путь миграции по версии Gitea

Запустите gitea --version, найдите свою строку и следуйте пути из третьего столбца. Всё остальное в этом руководстве — детали, стоящие за этими строками.

Заявления о совместимости версий взяты прямо из официальное объявление о совместимости Forgejo: Gitea вплоть до v1.21 может перейти на Forgejo с v7.0 по v10.0, а Gitea v1.22 может перейти на Forgejo с v8.0 по v10.0. Оба варианта ограничены версией v10.0 как последней поддерживаемой прямой целью.

За вопросом версии стоят три стратегии миграции, и полезно увидеть их до пошаговых инструкций:

• На месте, тот же сервер. Замените бинарник или образ контейнера на существующем сервере. Минимум усилий, если ваша версия это поддерживает; требует промежуточного шага через v10.0.
• Подготовка на новом сервере. Разверните новый сервер и используйте его как безопасную цель для метода миграции, соответствующего вашей версии Gitea. Это защищает исходный сервер Gitea и упрощает откат, но не обходит проблему схемы базы данных Gitea 1.23+.
• Миграция через репозиторий/API. Используйте инструменты миграции Forgejo, чтобы забрать репозитории со старого экземпляра Gitea. История git — это надёжная часть; метаданные, такие как issues, PR, метки, релизы, данные wiki и комментарии, следует рассматривать как «по возможности» и проверять по каждому репозиторию отдельно.

Поддерживаемый путь: Gitea v1.22 или более ранняя версия

Если у вас Gitea v1.22 или более ранняя версия, официальная документация по миграции описывают двухшаговый путь: перейти на Forgejo v10.0.x, затем обновить Forgejo v10 до текущего релиза. Первый шаг — прямая замена, поскольку Forgejo v10.x читает базу данных Gitea v1.22; второй шаг — обычное обновление Forgejo.

Есть два способа сделать это в зависимости от того, как Gitea работает на вашем сервере. Выберите тот, что соответствует вашей текущей настройке. Если Gitea работает как системный сервис, используйте нативный путь. Если Gitea работает в контейнере, используйте путь через Docker. Forgejo v10.x выступает прямой заменой для Gitea v1.22.x.

нативный путь (systemd)

Сначала сделайте резервную копию. Затем установите Forgejo v10.0.x, используя пакет вашего дистрибутива или бинарный релиз, зафиксированный на версии v10.0. Остановите Gitea перед копированием чего-либо. Работающая служба, пишущая в каталог данных во время копирования, повредит копию.

# Stop the running Gitea service before touching its data
systemctl stop gitea

Скопируйте конфигурацию и каталог данных в соответствующие расположения Forgejo, затем исправьте владельца. Файл конфигурации должен быть доступен для чтения группе forgejo; данные должны принадлежать пользователю forgejo.

# Copy the existing Gitea config to Forgejo's config path
cp /etc/gitea/app.ini /etc/forgejo/app.ini

# Back up the copied config before rewriting paths
cp /etc/forgejo/app.ini /etc/forgejo/app.ini.bak

# Update old Gitea data paths to Forgejo data paths
sed -i 's#/var/lib/gitea#/var/lib/forgejo#g' /etc/forgejo/app.ini

# Forgejo reads its config as the forgejo group; grant group write
chown root:forgejo /etc/forgejo/app.ini && chmod g+w /etc/forgejo/app.ini

# Copy the data directory and hand ownership to the forgejo user
rsync -aHAX --numeric-ids /var/lib/gitea/ /var/lib/forgejo/
chown -R forgejo:forgejo /var/lib/forgejo

Запустите Forgejo и включите автозапуск при загрузке.

# Start Forgejo and enable it at boot
systemctl start forgejo && systemctl enable forgejo

Перед обновлением с v10.0 очистите очереди, чтобы не потерять незавершённую работу во время скачка версии.

# Flush pending queue items before the version upgrade
forgejo manager flush-queues

Теперь обновите Forgejo v10.0.x до текущего релиза, заменив бинарный файл на v15 и перезапустив службу, следуя стандартному руководство по обновлению Forgejo. После обоих переходов запустите doctor, чтобы проверить базу данных и исправить то, что он может.

# Check everything; write a log you can read if something is wrong
forgejo doctor check --all --log-file /tmp/doctor.log

Читать /tmp/doctor.log прежде чем применять любое автоматическое исправление. Используйте --fix только когда вывод doctor указывает на конкретное исправление, которое вы понимаете, или когда вы следуете официальному пути устранения неполадок.

Если doctor не сообщает о критических ошибках, а веб-интерфейс отображает ваши репозитории, первая миграция завершена.

путь Docker / контейнер

Если Gitea работала как контейнер, запускайте Forgejo так же. Используйте образ Forgejo v10.x как прямую замену вашего образа Gitea v1.22.x, указав тот же том данных и базу данных. Сначала убедитесь, что версия Docker не ниже 20.10.6. Более старые версии дают непредсказуемое поведение с контейнерами Forgejo.

Одна деталь, специфичная для контейнеров, о которую спотыкаются люди: переменные окружения. Forgejo сохраняет префикс GITEA_ для совместимости, но документация рекомендует передавать оба префикса, чтобы ваша конфигурация пережила будущую версию Forgejo, которая откажется от старых имён.

# docker-compose.yml (excerpt): pass both prefixes for forward compatibility
environment:
  - GITEA__database__DB_TYPE=postgres
  - FORGEJO__database__DB_TYPE=postgres
  # ...repeat the dual-prefix pattern for every config override you pass

Для rootless-контейнеров данные должны принадлежать пользователю 1000 и группе 1000, что соответствует пользователю времени выполнения rootless-образа. После запуска контейнера на v10.x выполните тот же forgejo doctor check --all изнутри контейнера, затем обновите тег образа до текущего релиза v15 и перезапустите.

Если у вас Gitea v1.23 или новее

Здесь стандартные руководства заканчиваются, и именно здесь фактически находится большинство текущих установок. Официально поддерживаемого прямого пути с Gitea v1.23+ не существует, поэтому каждый из вариантов ниже либо основан на сообществе, либо связан с потерей данных. Прежде чем запускать любой из них, сделайте полную резервную копию каталога данных и базы данных и убедитесь, что можете её восстановить. Эти подходы изменяют production-данные; резервная копия — ваша единственная возможность отменить изменения.

Эти три варианта различаются по риску и по тому, сколько данных они сохраняют. Выберите тот, чей компромисс вам приемлем.

Вариант A: понижение версии схемы SQL / патч версии

Самый узкий обходной путь — понизить версию схемы базы данных так, чтобы Forgejo v10 воспринимал её как базу данных v1.22.

Примечание: не считайте обновление номера версии полноценным понижением версии само по себе. Записанная версия миграции и фактическая схема должны совпадать. На Gitea 1.23.x сначала протестируйте полное понижение версии на копии и сравните схему, прежде чем направлять на неё Forgejo.

Один из мейнтейнеров Forgejo описал SQL в issue #7638 на Codeberg:

-- Downgrade the recorded schema version to the v1.22 baseline (PostgreSQL/MySQL)
UPDATE version SET version=305 WHERE id=1;

После этого вы следуете поддерживаемому пути, как если бы у вас была v1.22. Важная оговорка: мейнтейнер подтвердил это конкретно для Gitea v1.23.1, а не для всей линейки v1.23.x. Номер версии схемы важен буквально; применение неверного целевого значения к неподходящему релизу Gitea может привести базу данных в состояние, из которого её не восстановит никакая миграция. Это касается PostgreSQL/MySQL, официально не поддерживается и не тестировалось как общая процедура.

Совет: прямая установка version=305 пропускает миграцию 304→305, которая изменила способ кодирования секретов TOTP. issue #8210 на Codeberg документирует, что это повреждает двухфакторную аутентификацию у затронутых пользователей. Решение — установить версию в 304 и дать миграции выполниться, либо очистить строки таблицы two_factor, чтобы пользователи заново прошли регистрацию. Не пропускайте этот шаг, если хоть одна учётная запись использует TOTP.

Вариант B: последовательные скрипты понижения SQL (Gitea 1.24–1.25.2)

Для версий между 1.24 и 1.25.2 одного патча версии недостаточно: схема прошла через несколько промежуточных состояний. Скрипты сообщества по адресу xlrl/prepare-gitea-migration-to-forgejo откатывают схему через промежуточные версии до v1.22, после чего вы идёте по поддерживаемому пути. Эти скрипты — работа сообщества, а не авторитетная процедура, и они нацелены в первую очередь на SQLite. Запускайте их только на базе данных, резервную копию которой вы уже сделали.

Вариант C: миграция через API репозиторий за репозиторием (Gitea 1.26+ или любая версия)

Путь через репозиторий/API наиболее надёжно сохраняет данные Git. В зависимости от источника, прав доступа и метода миграции опциональные метаданные, такие как issues, pull request'ы, метки, milestones, релизы, данные wiki и комментарии, тоже могут быть доступны, но относитесь к этому как к «по возможности» и проверяйте по каждому репозиторию отдельно. Для архива, где важен только код, этого обычно достаточно; для сервера, где трекер issue — это память команды, протестируйте перенос метаданных, прежде чем окончательно выбирать этот путь.

Два экспериментальных инструмента пытаются обеспечить более полную миграцию для 1.23+, но имеют собственные пробелы. pacnpal/gitea2forgejo (GitHub) делает полный дамп и синхронизацию через API, и для переноса зашифрованных полей требует совпадающий SECRET_KEY, но не переносит Personal Access Tokens, раннеры Actions, callback-URL вебхуков или 2FA. nicoverbruggen/gitea-to-forgejo (GitHub) — экспериментальный инструмент на базе Podman, переносящий пользователей, ключи, организации, репозитории, issues, PR, релизы и зеркала, но не токены 2FA, данные времени выполнения Actions или подвисшие манифесты пакетов OCI. Считайте оба инструмента экспериментальными и сверяйте результат с таблицей переноса ниже.

Вывод раздела: официально поддерживаемого прямого пути с Gitea 1.23+ не существует. Выберите вариант, чей компромисс по потере данных вам приемлем, и сделайте резервную копию перед началом.

Миграция на новый сервер безопаснее, но не обходит рубеж версий

Новый сервер — самое безопасное место для подготовки и проверки миграции, но это не отдельный путь совместимости схем. Если ваш источник — Gitea v1.22 или более ранняя версия, сначала установите Forgejo v10.0.x на целевом сервере, восстановите или скопируйте туда данные Gitea, дайте Forgejo выполнить поддерживаемые миграции базы данных, а затем обновите этот экземпляр Forgejo v10 до текущего релиза Forgejo.

Если ваш источник — Gitea v1.23 или новее, не восстанавливайте базу данных Gitea напрямую в текущую Forgejo, ожидая, что она запустится. Вам всё равно понадобится один из неподдерживаемых подходов для 1.23+, описанных выше: поэтапное понижение или откат SQL, инструмент миграции сообщества или миграция через репозиторий/API. Новый сервер снижает риск отката, поскольку исходная машина с Gitea остаётся нетронутой; но он не устраняет необходимость решать несовпадение версий базы данных.

Именно здесь Forgejo в один клик от Cloudzy app может помочь: используйте его как чистый целевой экземпляр, затем выполните метод миграции, соответствующий вашей версии Gitea. Образ из маркетплейса Cloudzy даёт вам готовую цель Forgejo на нашем высокопроизводительном VPS, так что вы можете сосредоточиться на восстановлении, проверке и переключении, а не на первоначальной установке. План миграции по-прежнему зависит от того, находитесь ли вы до или после рубежа Gitea 1.22.

Что переносится, а что нужно сделать заново

Часть ваших данных переносится автоматически, часть — только при выполнении определённого условия, а часть не переносится никогда и должна быть воссоздана вручную. Знание того, что к какой категории относится, ещё до начала — это разница между чистым переходом и неделей растерянных пользователей.

Сильнее всего бьют четыре момента, поскольку они ломаются незаметно или затрагивают каждого пользователя, так что отнеситесь к ним осознанно: пользователям следует пересоздать или проверить свои Personal Access Tokens, вам нужно заново зарегистрировать раннеры Actions под новым именем хоста, нужно удалить поисковый индекс Bleve, чтобы Forgejo пересобрал его с нуля, и нужно переписать любые uses: короткие ссылки в ваших workflow Actions на полные URL GitHub, поскольку Forgejo и Gitea забирают actions из разных зеркал, и относительная ссылка указывает не туда.

Совет: если вы запускаете Gitea и Forgejo параллельно во время миграции и оба указывают на один и тот же экземпляр Redis, переключите Forgejo на Redis db=1 перед началом. Оба по умолчанию используют db=0, и если они его делят, Gitea поглощает события миграции Forgejo и разрушает очередь миграции. (blog.mei-home.net documents this exact failure.)

Вывод раздела: Personal Access Tokens, раннеры Actions, deploy-ключи для отдельных репозиториев и поисковый индекс Bleve всегда переносятся вручную. Внесите их в план миграции как задачи, а не как то, о чём вспоминают потом.

Убедитесь, что миграция прошла успешно

Начните с doctor, затем проверьте цифры, затем протестируйте то, что пользователи реально делают. Doctor выявляет проблемы на уровне базы данных; ручные проверки выявляют потерю данных и проблемы доступа, которые doctor не видит.

1. Запустите forgejo doctor check --all --log-file /tmp/doctor.log, затем прочитайте лог перед внесением изменений. Используйте --fix только для конкретного исправления, которое вы понимаете.
2. Убедитесь, что количество репозиториев, количество issues и PR, а также количество и общий размер объектов LFS совпадают с показателями до миграции. Несовпадение здесь означает, что что-то не перенеслось.
3. Протестируйте SSH push и pull. Если у клиентов возникает несовпадение host-ключа, значит вы не скопировали /etc/ssh/ssh_host_* на новый сервер.
4. Войдите и убедитесь, что 2FA работает для учётной записи, которая её использует. Если TOTP не работает, см. оговорку к Варианту A выше.
5. Пересоздайте Personal Access Tokens, перерегистрируйте раннеры Actions и запустите тестовый workflow.

У нескольких симптомов, возникающих после миграции, есть известные причины. Отсутствующий favicon или логотип означает, что ресурсы брендинга всё ещё находятся в public/assets/img/, а не в custom/, где Forgejo теперь их ожидает. Ошибки 404 на маршрутах пакетов указывают на неверно настроенные пути хранения. Сбой Actions с сообщением "repository not found" — это uses: проблема зеркал. Переключитесь на полные URL. Пустая страница или ошибка 500 после входа при базе данных SQLite означает, что вы ниже минимума, который документация по обновлению установила на уровне Forgejo v1.19.3-0.

Когда имеет смысл остаться на Gitea

Миграция — это выбор, а не обязанность. Если вы уже прошли рубеж версий и сложность миграции перевешивает выгоду от управления или функций в вашей ситуации, остаться на Gitea — вполне законный выбор. Gitea активно поддерживается (несколько релизов в месяц, на данный момент версия v1.26.4), а CommitGo предлагает коммерческие варианты, включая Gitea Enterprise, Gitea Cloud и сертификацию SOC 2 Type 2 для команд, которым они нужны.

Есть ещё вопрос промежуточного EOL, который стоит честно взвесить. Поддерживаемый прямой путь требует ненадолго установить Forgejo v10.0, которая находится в статусе EOL с апреля 2025 года. Это приемлемо как временный шаг миграции, от которого вы сразу же уходите дальше, но некоторые администраторы будут против этого по соображениям политики. Для них миграция через репозиторий/API в свежий экземпляр Forgejo может полностью избежать шага через EOL, тогда как поэтапная миграция на новом сервере всё равно зависит от выбранного метода миграции.

Если ваша причина для перехода — активность разработки, данные подтверждают, что Forgejo более активный проект: анализ от honeypot.net насчитал 3 039 коммитов Forgejo против 1 228 коммитов Gitea за период с июля 2024 по май 2025 года, и 232 контрибьютора Forgejo против 153 у Gitea за год, закончившийся в мае 2025 года. Это лишь один сигнал среди прочих; взвешивайте его вместе с риском вашей миграции, а не считайте решающим.

Вывод раздела: миграция не обязательна. Решение — это выбор между предпочтениями по управлению и активности проекта и риском миграции, и оба варианта имеют право на существование.

Выберите свой путь и сначала сделайте резервную копию

Ваш путь миграции сводится к одному числу: версии вашей Gitea. На v1.22 или более ранней вы идёте по поддерживаемому двухшаговому пути через Forgejo v10. На v1.23 или новее вы выбираете обходной путь исходя из приемлемой для вас потери данных: понижение версии SQL/схемы, скрипты сообщества, миграция через репозиторий/API или поэтапная миграция на новый сервер. Какой бы путь вы ни выбрали, сначала сделайте резервную копию каталога данных и базы данных, запустите forgejo doctor после, и убедитесь, что количество репозиториев, issue и объектов LFS совпадает с тем, что было изначально.

Определите свою версию, сделайте резервную копию и следуйте соответствующей строке. Путь сложнее, чем обещали старые руководства, но он чётко определён, как только вы понимаете, где находитесь относительно рубежа версий.

Часто задаваемые вопросы

Можно ли обновиться напрямую с Gitea на Forgejo?

Да, если вы используете Gitea v1.22 или более раннюю версию: обновитесь напрямую до Forgejo v10.0, затем обновите Forgejo v10 до текущего релиза. Нет, если вы используете Gitea v1.23 или новее. Forgejo v10.0 была последним релизом, поддерживающим прозрачное прямое обновление, поэтому более новые версии Gitea вместо этого требуют обходного пути.

Какая версия Gitea совместима с Forgejo?

У Gitea v1.22 и более ранних версий есть поддерживаемый прямой путь обновления до Forgejo (вплоть до Forgejo v10.0, а затем дальше до текущей версии). У Gitea v1.23 и новее нет официально поддерживаемого прямого пути, поскольку Forgejo прекратила поддержку прозрачных обновлений с Gitea v1.23+ начиная с релизов после v10.0.

Могу ли я перенести данные из Gitea 1.26 в Forgejo?

Да, но не через поддерживаемое прямое обновление. Ваши варианты: миграция через репозиторий/API, где история git — надёжная часть, а метаданные нужно тестировать по каждому репозиторию, экспериментальный скрипт миграции или поэтапная миграция на новый сервер с использованием одного из неподдерживаемых методов для 1.23+ выше. Официально поддерживаемого пути обновления на месте с Gitea 1.26 не существует.

Переносятся ли мои Personal Access Tokens?

Запланируйте пересоздание или обновление Personal Access Tokens после миграции. Некоторые пути миграции не сохраняют их, а даже если токены остаются на месте, пользователям стоит проверить их области действия, прежде чем снова на них полагаться. Все скрипты и интеграции, использующие старые токены, нужно протестировать и обновить после перехода.

Будут ли работать мои workflow'ы Gitea Actions в Forgejo?

В основном да, с двумя обязательными исправлениями. Workflow uses: короткие ссылки перестают работать, потому что Forgejo и Gitea забирают actions из разных зеркал. Замените их на полные URL GitHub (например, uses: https://github.com/sammcj/dotenv-output-action@main. Также нужно заново зарегистрировать раннеры Actions, поскольку их токены регистрации привязаны к старому имени хоста.

А как насчёт миграции с Gogs на Forgejo?

Это отдельная миграция со своим путём, и она выходит за рамки этой статьи. Данное руководство посвящено именно миграции с Gitea на Forgejo; если источник — Gogs, обратитесь к официальной документации Forgejo по миграции за процедурой, специфичной для Gogs.