Migration Guide

Why Migrate?

git is a near-ubiquitous version control system of choice for many software projects, but that doesn’t mean all projects need to be hosted the same way. In fact, git is itself designed to be service-independent. That doesn’t change the fact that it’s much easier to manage with a service - and many services offer features on top of git that make collaboration far easier - things like issue tracking, pull request management, documentation hosting, project management and continuous integration.

The platform we choose for hosting says a lot about the values of our ecosystem. Codeberg’s open-source roots and non-profit status help assure us that their interests are in the collaboration. Further, Codeberg’s tooling is moving toward federated interoperability which will make it even easier to work across services in the future.

When you migrate your projects you are helping to build enthusiasm and prove the viability for a more open platform for code development.

Migrating Step-by-step

Leverage Codeberg’s excellent documentation

Codeberg provides excellent documentation with instructions for migrating repositories. We’ll follow this closely. It is a great resource if you want more detailed instructions.

Step 1. Starting a Migration

  1. On Codeberg, wherever you would start a new repository you will also find a nearby option to start a New Migration.

  2. Start a New Migration and you’ll be greeted with a catalog of services to migrate from.

    Note

    As the R ecosystem is largley based on GitHub, we’ll use that as an example, though the workflow would be largely the same regardless of service.

Step 2. Configuring the Migration

You’ll land on a platform-specific form where you are asked to provide basic information about the repository you plan to migrate from and be asked to provide credentials so that Codeberg can access the repo on your behalf.

You’ll be asked to provide:

  • The HTTP(S) git clone url (ie https://github.com/org/repo.git)

  • An access token
    For simplicity, you can use GitHub’s “classic” Tokens, which are easier to set up, but grant sweeping access. We will delete it shortly after we’re done here to avoid any risks.

  • Which parts of the repository you want to migrate. Unless you have reason to leave something behind, you might as well check all the boxes.

  • And a bit of information about the new repository you plan to migrate to: an owner, repository name, whether it should be private and an optional description.

Step 3. Migrate!

Click Migrate repository!

Once you start the migration you’ll land on a splash page to monitor the status. It should only take a couple minutes.

Important

After the migration is complete, you should delete the access token that you created to perform the migration. we won’t need it again! If needed again you can always generate a new one.

Remember, you should also change your local git remote setup. If you have a clone on your local desktop (or any other computer) you can:

1git remote -v
git remote set-url origin git@codeberg.org:your_user/your_repos.git 
2git remote -v
1
Check to see your current remotes
2
Confirm that you added a new origin

(Optional) Step 4. Mirroring Back to the Source Repository

Maybe you work with contributors who aren’t yet ready to migrate to Codeberg. Maybe you had a development package that people were installing using {remotes} or {pak} and you don’t want to break their installation process. Maybe you want to keep the visibility, knowing that GitHub still attracts a large user base?

We can work on Codeberg without sacrificing the benefits of GitHub by mirroring our repository back.

  1. In your new codeberg repository settings, scroll down to find Mirror Settings

  2. You’ll be asked for a git url and authentication. This should be either

    Tip

    (Recommended) A SSH git clone url, provided with an authentication token.

    or

    Warning

    An HTTP(S) git clone url, provided with your username and password

    Even if you’re not comfortable with SSH generally, Codeberg will generate the key on your behalf. We only have to enter it in the right place on GitHub.

  3. You can choose when the synchronizing happens. For most, it is a good idea to check the box for Sync when commits are pushed.

  4. Click Add push mirror, at which point you’ll see a new entry in the mirrors listing.

  5. If you used SSH authentication, you’ll be provided with a link to copy your public key.

    Copy this public key and register it back on GitHub so Codeberg can act on your behalf to synchronize repositories. Give it a meaninful name so you remember it’s being used to manage your mirror.

  6. (Optional) If you had GitHub actions configured, your mirror will still be executing those actions so long as their configuration files live in .github/workflows. You can choose at this point whether you want to continue using GitHub actions by way of the mirror, or whether you’d prefer to migrate to Codeberg’s continuous integration tool, Woodpecker CI - or both! Even if you’re not paying for these services, remember that they’re consuming resources and generating emissions, so please be a mindful citizen of the global computing world and consume only what you need.

Next Steps

Add a Migration Notice

Whether you mirrored or left the old repository as is, you should let new visitors to your old repository know that it has moved. You should let your visitors know what they can expect regarding new issues and how you would like them to contribute.

If you left it as-is, you can edit the README.md.

If you mirrored your repository, you can tuck a GitHub-specific message in .github/README.md.

Update your Badges

If you had badges that reported the status of GitHub actions, those will continue to work so long as you have mirrored your repository back to GitHub and continue to run those actions.

However, if you choose to migrate to Woodpecker CI, it will automatically generate a pipeline status badge, which indicates an overall status for all workflows. You can find this badge in your repository’s CI settings on ci.codeberg.org.

Update your R Package GitHub Actions

Codeberg’s most accessible continuous integration services run on a system called Woodpecker CI, but it will require a few steps to configure.

  1. Copy r-pkg-standard.yml into your projects .woodpecker directory. This will add a typical R package continuous integration setup, including

    • R CMD check
    • unit testing,
    • code coverage calculation
    • pkgdown documentation building
    • Codeberg pages deployment
  2. Head to ci.codeberg.org to enable Woodpecker CI for your new repository.

  3. (Optional) Enable deploying to Codeberg pages. Allowing Woodpecker CI to push changes back to the pages branch, and thereby deploying to Codeberg pages, requires that we give Woodpecker CI a key to our repository. See the instructions at r-codeberg/woodpecker-ci#deploy for detailed instructions.