How to Migrate Repository from GitLab

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 GitLab 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 GitLab 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 GitLab 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 GitLab 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 GitLab 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 GitLab over to Codeberg, which is also based on Forgejo and supports native migration of repository contents, issue tickets and pull requests from GitLab using the instructions provided here — with some minor changes here and there.

Procedure

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

Create GitLab Personal Access Token

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

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

  3. Head over to the Settings > Access tokens page from the extended sidebar. migration gitlab 02

  4. Click on the Add new token button on the first section. migration gitlab 03

  5. Fill in the required information and select the necessary ACLs (Access Control Lists). migration gitlab 04

  6. Click the Create button to generate the personal access token.

  7. Copy the generated personal access token and keep it safely stored for use in the migration process. migration gitlab 05

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 gitlab 06

  3. Click on the New migration button to begin the migration process. migration gitlab 07

  4. Click on the GitLab button at the top of the migration page. migration gitlab 08

Configure Repository Migration

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

    1. Repository URL: Enter the GitLab repository URL

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

    3. Repository Name: Enter the desired name for the migrated repository

    4. Description: Copy the repository description from GitLab (optional) migration gitlab 09

  2. Click on the Migrate repository button to start the migration. migration gitlab 10

  3. Wait for the migration to complete. Monitor the progress and verify successful migration. migration gitlab 11

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 GitLab-specific features have been properly converted to Forgejo equivalents.

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