Home

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:

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, feeding it this very outdated starting point as inspiration. But I totally understand if not everyone is comfortable with using AI. 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.

Once I fixed these issues (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. 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!

Literally

1. Back up instance config and data
2. Swap out ELF for same or newer Forgejo version.

Forgejo past 10.0.x is not compatible with Gitea’s database schema. Have you tried it?

No

I haven’t either. 😄 But I’m just taking Forgejo’s docs on this at their word.

Thanks for writing this up. I went through the same migration last year and can confirm — it is not as smooth as “just swap the binary” anymore since the hard fork.

A few extra tips that saved me headaches:

• Backup everything first — obvious but worth emphasizing. Dump the database AND copy the entire data directory. pg_dump if you are on Postgres, or just copy the SQLite file.
• Check your Gitea version first — Forgejo migration paths assume specific Gitea versions. If you are on an old Gitea, you might need to step through intermediate Gitea versions before jumping to Forgejo.
• Webhooks and integrations — These survived the migration for me, but the API tokens did not. Had to regenerate them all.
• Runner compatibility — If you use Gitea Actions/runners, make sure to switch to Forgejo’s runner binary too. They have diverged enough that mixing them causes subtle issues.

Overall though, Forgejo has been great post-migration. More responsive to community issues and the federation work they are doing is exciting.

Using an LLM to do a database migration is like asking your neighbour’s kid to file your taxes.

Yes. But this is a lot. It may be easier to use Forgejo’s built in migration tools, to copy over repositories along with their issues and other info. You would have to rebuild the admin parts of the site, like “organizations” and user privileges. (Well if you are using oauth and mapping users from oautb groups then you don’t…). And I don’t know if it’s automated for a many, many repos. But it’s just a click click click in the gui.

I remember there was a tool, I think it was related to forgefed, that could do batch repo migrations via the cli. I can’t find it anymore though.

Lol that’s a good idea… I hate doing taxes!

That would be ideal if it worked, yeah. But personally I wouldn’t want to manually recreate the bits that it didn’t support migrating. I realize everyone’s instance and situation is different.

I’m staying with Gitea. They’ve created the Ltd. so they can sell professional support as most businesses will want a proper invoice. I don’t see anything wrong with that. Also, ForgeJo was promising federation which is still a WIP several years later. And, the one time I’ve tried ForgeJo it shit itself when I’ve added an emoji to my username. For some reason Gitea didn’t have any problem with that.

Personally, I think it’s great to have multiple options in this space. I think we can all agree that self-hosting (or using Forgejo/Gitea on a smaller platform, e.g. Codeberg) is preferable to centralizing absolutely everything on Microsoft GitHub.

And you love going to jail for gross tax fraud?

I think you underestimate how much of step up it would be for the neighbor’s kid to do my taxes.

The time to do this was before the hard fork.

The easy way to do this is make your user(s) and use Forgejo’s migration functions. Why would you muddy this up like this? Just nuke and pave, it would take a tenth of the time and be a hell of a lot less chancy in their long term.

The best time to do was before the hard fork. The second best time was was, well, now. Also, I am the user(s) of this former Gitea instance, just in terms of who owns the repos on it. And like I said above, I didn’t want to lose all of the data that the built-in migration feature wouldn’t migrate.

There’s a better way

Start with the last Forgejo version to be compatible with with Gitea and then slowly upgrade Forgejo one version at a time. This should be trivial to do and can be scripted easily.

If you are not a Gitea customer, you are not being informed of security updates in a timely manner:

Gitea repeatedly makes choices that leave Gitea admins exposed to known vulnerabilities during extended periods of time. For instance Gitea spent resources to undergo a SOC2 security audit for its SaaS offering while critical vulnerabilities demanded a new release. Advance notice of security releases is for customers only.

https://forgejo.org/compare-to-gitea/#security

Also, ForgeJo was promising federation which is still a WIP several years later.

Oh no, it doesn’t do the big feature™. I guess it’s unusable now.

I wish people would realize that software still works and is excellent even without the various flagship features. I use Kubernetes on a single node. I know there are people who use matrix without federation and e2ee because it’s actually a really good chat app, it just struggles with the performance demands of federation, and the e2ee ux isn’t quite there yet.

I don’t understand. How would that help switching from a Gitea 1.25.x instance?

Shoot your right

Never mind I guess. You would need to downgrade which I don’t think is possible

Has Gitea even given any indication that they want to work on federation themselves?

If you are not a Gitea customer, you are not being informed of security updates in a timely manner

I don’t need a notification of issues, I need a notification of when there’s a new version to roll out. And that can be solved by using things like WatchTower or setting up release notifications on GitHub.

And, of course, a comparison hosted on ForgeJo’s webpage will make it out that they’re “the better choice”.

Also, ForgeJo was promising federation which is still a WIP several years later.

Oh no, it doesn’t do the big feature™. I guess it’s unusable now.

Well, that was the one big distinguishing thing between the two, back when ForgeJo was the new kid on the block. ForgeJo wanted to make it a priority to implement federation.

And I never said it’s unusable - it’s just that I, personally, don’t see any reason to switch from Gitea to ForgeJo.

I just spun up Forgejo and pushed up all my repos by hand because I’m lazy.

I wrote a python handler to query the GItea api and either mirror from source repos that were a straight mirror, or full clone/standalone local repos. Also handled creating orgs (using the forgejo api), since I wasn’t going to do any of that by hand.

That sounds pretty nice. Did it also handle issues and comments and stuff?

Sounds like not lazy at all. If anything more work depending on the number of repos!

Well, not officially supported anyway…

I had like 10 repos and nothing of much value in the DB, so it was quick to create the repos and push them up.

I didn’t have any to move, so I didn’t allow for that. I’d assume not though.