How to Migrate Repository from Pagure

Purpose

This document outlines the steps required to migrate repositories from Pagure 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 the legacy Pagure service 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 Pagure 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.

Do NOT create or use an API key for standard repository migration. The API key is only needed for migrating private tickets. Using an API key in the standard migration will cause the migrator to import only private tickets instead of the full repository content. If you haven’t set the repository to private, these private tickets will become publicly visible.

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

Procedure

The migration process involves two main steps: accessing the Fedora Forge migration tool and configuring the repository migration.

Access Fedora Forge Migration Tool

  1. Log into Fedora Forge using your Fedora Accounts credentials and navigate to the destination organization where you want to create the migrated repository.

  2. Click on the New migration button to begin the migration process. pagure migration new migration button

  3. Click on the Pagure button at the bottom of the migration page. pagure migration select pagure source

Configure Repository Migration

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

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

    2. Clone URL: Enter the Git clone URL from your Pagure repository.

    3. Description: Copy the repository description from Pagure (optional).

    4. Visibility: Set to public for publicly accessible content.

    5. Leave the token field empty - this is crucial for standard repository migration. pagure migration form filled

      Do NOT enter an API key in the token field. If you provide an API key here, the migrator will only import private tickets instead of the full repository content (code, public issues, pull requests, etc.). This will result in an incomplete migration. Additionally, if you haven’t set the repository to private, these private tickets will become publicly visible, potentially exposing confidential information.

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

  3. Wait for the migration to complete. This creates a repository with all publicly accessible data. pagure migration completion success

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.

Next steps

Based on early migrations, we offer this list of recommended next steps after repository migration.

  1. Copy over the project URL for Forge manually. From Pagure project → Settings → Project Details → Project’s url into Forge project → Settings → Repository → Website.

  2. Migrate assignees and dependencies. Verify that it worked correctly. Also inspect script output.

  3. Use pagure_add_migration_comment.py to add a migration comment to all tickets in Pagure. Verify that they it worked correctly. Also inspect script output.

  4. Use forge_convert_labels.py to convert priority labels to the Forge standard ones: the migration tool creates separate priority labels for each repository. Check your organization has the Forge standard labels first, with the IDs listed in the script. If your project’s priorities don’t match those the script can handle, please send a pull request.

  5. In Pagure project → Settings → Project Options, enable Issue tracker read only and disable Pull requests.

  6. Replace the README contents of the Pagure repo with a message:

    ** This project has been moved to: $NEWURL **

This repository is now in archive mode only. There will be no further responses to any issues or pull requests in this repository. The development will only be taken forward in the new repository.

  7. In Forge project → Settings → Units, disable the Wiki unless you really want it. You may also want to adjust the Merge styles and Default merge style to your preference.

  8. If you use any kanban boards in the source repo, you need to re-create them manually in the new Forge repo. In Forge they are called projects and can be created at the organization and/or repository level.

  9. Go through all source code, internal and external documentation, RPM spec files, and any other locations, find references to the old repo and replace it with the new URL. This might take a while, perhaps file a ticket for this so that you don’t forget about it to do it later.

  10. If your repo uses CI, migrate it. You cannot use Zuul CI with Forge as you could with pagure.io. The easiest alternative is Forgejo Actions, which works much like GitHub Actions. You can get inspiration from Adam’s howto blogpost, the fedfind repo and Forgejo Actions documentation.

  11. The forge-helpers repository contains scripts for converting the custom story_points field to a label and converting migrated priority labels to Forge-standard ones, but it’s likely you can’t use either directly. The story point script is only applicable if you had the custom story_points field in your Pagure repo. The label conversion script will only work as intended if you have the Scrum labels in your Forge organization and they have the same IDs the script expects - check this before running it.

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