How to Migrate Repository from GitHub

DRAFT DOCUMENTATION: This documentation is currently in draft form and may not be fully tested and correct. Please verify all procedures before use and report any issues or inaccuracies.

Purpose

This document outlines the steps required to migrate repositories from GitHub to Fedora Forge, ensuring proper transfer of repository contents, issue tickets, and pull requests to the new Forgejo-based platform.

Scope

This procedure applies to Fedora Project contributors who need to migrate repositories from GitHub to the new Fedora Forge platform. This includes subprojects, Special Interest Groups (SIGs), and other official Fedora Project repositories.

Prerequisites

  • Repository Access: You must have access to the source repository on GitHub and the necessary privileges to create repositories in the target organization on Fedora Forge.

  • Organization Permissions: You must have the ability to create repositories under the target namespace in Fedora Forge. If you don’t have these privileges, consult a member from the relevant subproject or SIG, or contact the Fedora Infrastructure team.

  • Personal Access Token: You will need to create a personal access token in GitHub for the migration process.

As the Forgejo-based Fedora Forge houses only those repositories that are instrumental in the development, testing, maintenance and operating of the Fedora Project’s offering of Fedora Linux, please use this for those repositories only — and not for any other personal repositories.

As Forgejo does not support the creation of privately restricted issue tickets at this time, please take extra care while migrating those away from the source namespace on GitHub to ensure that confidential information contained in those issue tickets are not accidentally released out in the process.

We recommend migrating your other personal repositories present on GitHub over to Codeberg, which is also based on Forgejo and supports native migration of repository contents, issue tickets and pull requests from GitHub using the instructions provided here — with some minor changes here and there.

Procedure

The migration process involves three main steps: creating a GitHub personal access token, accessing the Fedora Forge migration tool, and configuring the repository migration.

Create GitHub Personal Access Token

  1. Log into GitHub and navigate to the source repository you want to migrate.

  2. Take note of the repository URL for later reference. migration github 01

  3. Click on your portrait in the top-right corner and navigate to user settings. migration github 02

  4. Head over to the Developer settings at the bottom of the sidebar. migration github 03

  5. Under the Personal access tokens section, select Tokens (classic). migration github 04

  6. Under the General new token dropdown, click on the first option. migration github 05

  7. Provide your credentials to log into GitHub if required to do so. migration github 06

  8. Fill in the required details properly according to the request. migration github 07

  9. Select the sought repository from the Repository access section. migration github 08

  10. Choose your migration scope:

    1. If you want to migrate only the public repos, select the first option. migration github 09

    2. If you want to migrate the entire namespace, select the second option. migration github 10

  11. Click on the Generate token button and confirm again when asked. migration github 11

  12. Copy the generated personal access token and keep it safely stored for use in the migration process. migration github 12

Access Fedora Forge Migration Tool

  1. Log into Fedora Forge using your Fedora Account credentials.

  2. Navigate to the destination organization where you want to create the migrated repository. migration github 13

  3. Click on the New migration button to begin the migration process. migration github 14

  4. Click on the GitHub button at the top of the migration page. migration github 15

Configure Repository Migration

  1. Fill in the migration form with the information from your source repository:

    1. Repository URL: Enter the GitHub repository URL

    2. Personal Access Token: Enter the token you created earlier

    3. Migration Items: Select what to migrate (repositories, issues, pull requests, etc.) migration github 16

  2. Click on the Migrate button to start the migration.

  3. Please be patient while the migration progresses gradually. Monitor the progress. migration github 17

  4. Wait for the migration to complete and verify successful migration. migration github 18

Verification

  • Confirm that the migrated repository appears in the target organization on Fedora Forge.

  • Verify that all repository contents (code, branches, tags) have been successfully migrated.

  • Check that issue tickets and pull requests have been transferred correctly.

  • Test repository access permissions for team members.

  • Verify that the repository is accessible via Git clone operations.

  • Confirm that all GitHub-specific features have been properly converted to Forgejo equivalents.

Want to help? Learn how to contribute to Fedora Docs ›