Migrating from Gitea to Forgejo
This page is the operational side of the move. If you are still deciding whether to make it, the governance, licensing and feature comparison is on Forgejo vs Gitea.
The short version: migrating from Gitea to Forgejo is an upgrade in place, not an export and import. Forgejo takes over the existing database and data directory. There is no repository re-import, no re-cloning by your developers, and no change to remote URLs.
That makes it far less work than most platform migrations. It also means the usual upgrade discipline applies, because you are running schema migrations against your production database.
Before you start
Take a backup, and test restoring it. This is the one step people skip and regret. The migration runs database schema changes, and the rollback path is a restore, not a downgrade (see the warning below). A backup you have not restored at least once is a hypothesis.
Check your version path. Compatibility is not open-ended:
| From | To |
|---|---|
| Any Gitea version up to and including v1.22.x | Forgejo v10.0.x |
| Forgejo v10.0.x | Any newer Forgejo release |
So it is two steps, not one. Land on Forgejo v10.0.x first, confirm the instance is healthy, then continue up the Forgejo release line. Gitea versions newer than v1.22.x are past the point where the two codebases still line up: Forgejo became a hard fork in early 2024 and has diverged since.
Review your customizations. If you have patched templates or added custom CSS, diff your template directory against the stock one and note what you changed. Customizations are the most common cause of a migration that technically succeeds and visibly breaks.
Check your Docker version if you run in containers. Docker 20.10.6 or newer avoids a class of problems that are hard to diagnose from the symptoms.
The migration
1. Flush the queues.
forgejo manager flush-queues
Queues hold serialized data in a version-specific format, so anything still
pending when you swap versions may not be readable afterwards. If the command
times out, raise --timeout and run it again rather than moving on.
2. Swap the binary or the container image.
Replace the Gitea binary or image with Forgejo v10.0.x. Database migrations run automatically on first start.
Forgejo keeps the binary named gitea, with symbolic links, precisely so that
existing systemd units, scripts and cron jobs keep working. You do not need to
rewrite your service files as part of this step.
3. Verify.
forgejo doctor check --all --log-file /tmp/doctor.log
Then open the web interface and check the things a script cannot: a repository you care about, a pull request, a CI run, an SSH clone, and login through whatever authentication source you use.
4. Continue up the release line.
Once v10.0.x is healthy, upgrade to a current Forgejo release. If an upgrade spanning several versions fails, redo it one release series at a time to find which one is unhappy.
The one-way warning
Downgrading is not supported and is actively prevented. Once Forgejo has migrated the database, version checks block an older binary from starting against it. Going back means restoring your backup and losing anything written since it was taken.
Plan the maintenance window accordingly: the decision point is before you start Forgejo for the first time, not after.
What usually goes wrong
- Skipped or untested backups. The failure mode is not "the migration broke", it is "the migration broke and we could not go back".
- Custom templates. They survive the upgrade and then render against changed markup. Diff first.
- Version jumps. Trying to go straight from an old Gitea to a current Forgejo instead of landing on v10.0.x first.
- Pending queue items. Skipping the flush and finding out later.
- Authentication. LDAP, OAuth and SSO configurations deserve an explicit test after the move, not an assumption.
Where VSHN fits
We operate Forgejo in production and have run this path. Three ways to work with us, depending on how much you want to keep:
Keep running it yourself, with help for the move. We plan the version path, review your customizations, do a rehearsal against a restored copy of your data, and stay on the call during the maintenance window.
Hand over operations, keep your infrastructure. We run the instance on your cloud or on-premises platform: upgrades, backups, monitoring and incident response, with the data staying where it is.
Move to a managed instance. Codey is a dedicated Forgejo instance operated by VSHN in Switzerland from CHF 39 per month, with Forgejo Actions CI/CD, package hosting and backups included. If you are already planning a maintenance window to leave Gitea, moving to a managed instance costs about the same effort as moving to a self-hosted one.
Not sure which fits? Book a free migration assessment and we will map your current setup to a version path and a window.