Migrating from GitHub to Codeberg: A Step-by-Step Guide

For developers who have been hesitant to switch from GitHub due to perceived technical hurdles or concerns about readiness, a recent transition has provided valuable insights. I recently embarked on migrating several repositories from GitHub to Codeberg—a move driven by both personal preference and the desire for alternative hosting options. This journey uncovered some surprising findings that might just motivate others in similar situations.

Smooth Transitions: Issues, Pull Requests & Releases

The process of transferring issues, pull requests (PRs), and releases was surprisingly straightforward thanks to Codeberg's robust repository import feature from GitHub. The user experience is notably superior compared to manual workarounds often employed by developers looking to integrate data from other platforms into their repositories.

Importing these elements directly preserves issue numbers, labels, authorship details, ensuring a seamless transition without the need for extensive reconfiguration or loss of valuable metadata. This feature alone makes the initial migration less daunting and more user-friendly than anticipated.

The Nastiest Part: Continuous Integration (CI)

While transferring issues, PRs, and releases was relatively painless, setting up continuous integration (CI) posed a significant challenge. GitHub's free macOS runners and infinite capacity for public repositories have long been attractive features that many developers rely on.

To replace these benefits in Codeberg requires a different approach. Cross-compilation is recommended as an essential step to ensure compatibility across various platforms, especially if your project involves complex dependencies or specific build environments. Additionally, self-hosting a runner using Forgejo Actions can provide the necessary infrastructure for CI processes without relying on external services.

Forgejo Actions are particularly appealing due to their familiar interface and setup process, closely mirroring GitHub's Action workflow. However, users should be aware that while documentation is currently out of date, this tool offers a more stable alternative compared to Woodpecker CI, which might seem like the obvious choice given its presence on Codeberg.

For developers looking for a smoother transition and those who want to explore alternatives beyond GitHub, migrating repositories to Codeberg can be an attractive option. The initial steps of transferring issues, PRs, and releases are straightforward thanks to built-in tools, while CI challenges require some additional effort but offer long-term benefits in terms of control and stability.