A self-hosted forge is a great git remote and a poor GitHub replacement

What you can move, and what you cannot#

Repositories move easily. Issues, pull requests, releases and wikis move with a decent importer. What does not move is the network: the person who found your project through a GitHub search, filed a bug, and sent a patch because they already had an account. A self-hosted forge is an excellent git remote, a good private issue tracker, and a poor replacement for being visible where developers already are.

So do not frame it as a migration. Frame it as a primary and a mirror. Your forge is authoritative, your git push goes there, and a push mirror keeps a read-only copy on GitHub or Codeberg for discovery and for the day your server does not come back. Both Forgejo and Gitea do push mirroring in core. GitLab's pull mirroring is a Premium feature, which surprises people.

The second uncomfortable fact: if your forge runs on a machine in the same house as your laptop, you do not have an off-site copy of your code. A fire or a theft takes both. A git clone on the laptop is not the backup either, because it carries no issues, no releases, no LFS objects and no wiki.

The default#

Run Forgejo: one container, one volume, SQLite unless you choose otherwise, roughly 150 MB idle, serving a dozen developers on a 2 GB VPS without complaint. The reason is governance, not features. Forgejo belongs to Codeberg e.V. and has been GPL-3.0-or-later since v9.0 on 22 August 2024, so an open core split cannot be applied to it later. The cost is real: fewer eyes on the code, corporate legal reviews that flinch at GPL-3.0, and an Actions implementation that is thin next to GitHub's.

Do not take that advice in either of these cases. Your legal policy is permissive-only, or you are already on Gitea v1.23 or newer, where there is no supported direct migration and moving means exporting repository by repository. Stay on Gitea; it is the same software with a different owner. You want repositories, CI, a container registry, packages and environments in one upgrade unit and have the hardware for it: GitLab CE, with 8 GB minimum and 16 GB baseline per its own requirements page. Add Woodpecker CI when your forge's built-in CI runs out, Harbor only when you need scanning and RBAC over images, and code-server if the code should live on the server rather than the laptop.

The mistakes#

• Publishing port 3000 before finishing the installer. The first-run setup page is unauthenticated and the first account created becomes the instance administrator. Bind to localhost first, or pre-write app.ini with INSTALL_LOCK = true.
• Mapping host 222 to container 22 and forgetting SSH_PORT = 222. The clone URL comes from app.ini, not from Docker, so every developer copies a URL that times out. ROOT_URL behind a proxy has the same failure shape for webhooks and OAuth redirects.
• Restoring a dump into a different path. Every repository's git hooks contain the absolute path of the forge binary. Pushes then fail with an opaque hook error while the web UI looks healthy. Run the admin hook regeneration command after any move or restore.
• Backing up a running forge. The docs are explicit: shut down before gitea dump, or the database and the repository files diverge mid-copy and you find out at restore time.
• Trying SQLite in production and converting later. The documentation warns that engine conversion is not well tested. Pick PostgreSQL up front if you expect more than a handful of active users.
• Restoring GitLab without /etc/gitlab. gitlab-backup create deliberately excludes gitlab-secrets.json, so a restore comes up with every encrypted column unreadable: CI variables, integration tokens and two-factor seeds.
• Assuming deleted Harbor tags free disk. They do not until garbage collection runs, and Harbor goes read-only while it does.

Read next#

Forgejo vs Gitea has the governance argument in full, Gitea vs GitLab CE the size one. Replace GitHub covers the mirror-and-migrate shape end to end. Then Backups that actually restore for the dump, Moving a service to a new machine for the hook-path trap, and A security baseline for a home server before you hand any runner a Docker socket.