Here’s the background: I’d been using Gitea for open source project hosting for a quite a while. So when the Forgejo fork started up, I thought to myself: Eh, I’ll see how that all unfolds and maybe look into it at some point. After all, Forgejo is a soft fork, so I can just switch over whenever.

But then Forgejo became a hard fork while I was busy with other stuff, and before I knew it, It seemed too late to switch unless I wanted to lose all my tickets and stuff.

Then I saw this post and read this background and decided it was time for me to switch to Forgejo, hard fork be damned.

But I’m very stubborn, and I still wanted to keep all of my Gitea data intact. So here’s what I did, and what you could do too if you’re as stubborn and reckless as I am!

Step one: Create a SQL “migration” that downgrades the Gitea database from the modern version you’re using to the last version that Forgejo supports upgrading, Gitea 1.22.6, from back when Forgejo was still a soft-ish fork. That means you’re effectively rolling back each migration from Gitea 1.25 all the way through 1.24 and 1.23.

When I did this, I used an LLM (specifically MiniMax with OpenCode) to generate the reverse mega-migration, pointing it at the Gitea codebase and also feeding it this very outdated starting point as inspiration. But I totally understand if not everyone is comfortable with using AI for this. In fact, I really wasn’t either, but I figured this is a mostly mechanical one-off. If you don’t want to use AI, you can generate the reverse migration manually by combing through the migrations linked above.

I did find three mistakes the LLM made: 1. An off-by-one error in UPDATE version ... because the value should be the last migration number (298 in this case) plus one, 2. Some of the steps it generated to back out an individual migration were out of order, e.g. dropping the issue_pin table before copying data out of it, and 3. It apparently missed making one particular column (type in the review table) into an int instead of a varchar.

I should also note that there were some forward data migrations in the original Gitea migrations that could not be backed out, because the data simply wasn’t there anymore. I just skipped reversing those, because YOLO.

Once I fixed these issues as best I could (well, the ones I found ahead of time instead of after the fact), the mega-migration was ready to go.

(I’m not including the mega-migration here, because even if it worked for me, I don’t want to be responsible for people fucking up their systems if it doesn’t work for them. I’d much rather people be responsible for fucking up their own systems.)

Step two: Backup your Gitea database and files!!!

Step three: Stop Gitea and run the mega-rollback-migration against your Gitea database. This effectively downgrades the database to Gitea 1.22.6. You can optionally then deploy the Gitea 1.22.6 binary or container and start it up to poke around the Gitea web UI and verify that the downgrade worked. (Reminder that there are known security issues in this ancient version of Gitea, so maybe firewall off general web traffic temporarily?) Then stop Gitea again.

Step four: Replace the Gitea binary or container with the last release of Forgejo to support upgrades from Gitea, Forgejo 10.0.3. Start Forgejo and try out the web UI to make sure it’s working.

Step five: Upgrade your Forgejo binary or container to the latest release of Forgejo, 14.0.3 at the time of this writing. Restart Forgejo and hopefully enjoy your newly “upgraded” instance, complete with all of your repos and ticket history!

Some additional notes:

• You may have to alter any Gitea Action workflows to work with Forgejo Actions. This may be as simple as search and replacing gitea. with forgejo. in your workflow files.
• Forgejo does work with Gitea’s Act Runner, apparently. But you may also want to replace any Act Runner instances you have with Forgejo Runner, which should be relatively straightforward since there’s no database to migrate.