Migrate to Projects

The JFrog Project Migration Tool is a step-by-step wizard that automates the transition of existing repositories and access controls into a unified project structure. The tool maps legacy user actions directly to the resources they use and converts them into project-based role structures. It automatically designs a recommended target repository structure, combines local and remote repositories into Virtual Repositories, and provisions the new Project container and configurations without interrupting existing storage or breaking existing CI/CD pipelines.

For background on migration strategy and brownfield considerations, see Projects Migration Best Practices.

Prerequisites
To use Project migration, make sure you have:

• Platform Administrator role.

Create a New Migration

To migrate to Projects:

1. In the Administration module, go to Projects Migration and click New Migration.
   

   

2. In the Migration Name field, enter a name for the migration and a description to help you identify it, then click Continue to Wizard.

   
   
   

3. In Step 1: Define Project, select your preferences for the following fields. For more information and best practices, see Defining the Project Entity.

   When you are done, click Next to Step 2 >.

   
   

   

   
   

   • For 1. Choose project mapping, select how projects are divided in your organization: whether you have a project per team, per application, or any other division. This helps you decide which users and groups should be assigned to the project in the migration process.

     📘

     Note

     Make the architectural design decision on the right project mapping for your organization before starting the migration process, to ensure the mapping is aligned with your business structure and requirements. For more information, see Projects Best Practices.

   • For 2. Select project members, select the checkboxes next to the groups and users you want to include in your project. Use the search bar to find a specific user or group.

   • For 3. Name your project, Enter a Project Name, Project Key, and Project storage quota.

     Description	Field name	Example
     The name of the project, identifying its purpose and mirroring the mapping. Note the project key limitations: The characters :|?<>"*/@ are not allowed.	Project Name	ML Engineering US
     A unique identifier for the project.	Project Key	ml-eng-us
     The maximum storage allocated to the project. Note that this will not restrict your storage, and only send notifications when getting near the quota.	Storage Quota	50 GB

4. In Step 2: Select Permission Targets, select the checkbox for the existing permission targets from your environment that you want to use in your new project. The list shows the permission targets that the users and groups you selected in Step 1 are currently assigned to, so you can see which permission targets need to be mapped to the project. Use the search bar to find a specific permission target, or filter by the user or group that has that permission target applied. When you are done, click Next to Step 3 >.

   
   

   

   
   

   📘

   Note

   Any Local and Any Remote permission targets are not mapped to a project automatically, and must be handled manually. By definition, these permission targets do not provide the resource isolation that projects are designed to enforce, so they cannot be mapped to a specific project without potentially changing your existing access model.

5. In Step 3: Project Repository Structure, review the Creation Repositories Flow panel: to translate your permission targets into a project structure, the Project Migration tool creates a new local or remote repository for each permission target, and a virtual repository wrapper to provide easy access.

   Each new repository retains the same configuration as the source repository associated with the permission target. The virtual repository includes the source repository as well, so the source and target repositories coexist within the same aggregated virtual repository. Because no changes are made to the source configuration, your existing CI/CD pipelines continue to work without breaking changes.

   
   

   

   
   To modify the suggested structure:

   • The New Repository fields contain suggested names for the repositories: click the pencil icon to edit them if needed.

   • Click the Select stage dropdown menu to assign a stage to each of the repositories.

   • To resolve naming conflicts or alerts, address the items in the Conflicts & Alerts panel.

   • To configure the default virtual repository resolution order, click Order & Default.

   When the repository structure is ready, click Next to Step 4 >.

6. In Step 4: Projects Role Mapping, review the suggested project role for each member.

   
   

   

   
   

   The wizard maps each member's existing permission-target actions to a project role, using the Roles Mapping legend in priority order (the first matching condition wins):

   Priority	Actions	Suggested role
   1	Contains MANAGE	Project Admin
   2	READ	Viewer
   3	READ + ANNOTATE + WRITE, no DELETE	Contributor
   4	READ + WRITE + DELETE + ANNOTATE, no SCAN	Developer
   5	READ + SCAN, not matched above	Security Manager
   6	Any other actions	Empty (edit the role manually)

   For each member, confirm or change the role in the Select Role column, then click Next to Step 5 >.

7. In Step 5: Review & Start Migration, review the summary of all the repositories and roles that will be created as part of your project migration, and any conflicts in the Conflicts and Alerts widget.

   
   

   

   
   

   The summary is read-only: to fix any issues or make changes, click < Back to return to the step where you want to make the change.
   When you are satisfied with the migration, click + Start Migration to execute the migration.

Manage Existing Migrations

To view your existing migrations:

1. Go to Administration > Projects > Projects Migration, and find the Projects Migration table that contains all your existing migrations. You can use the search bar to find a specific migration, or click the table icon on the top right hand side to customize columns.

2. The Status column indicates the current state of each migration and determines which actions are available in the options menu (three dots):

   1. Not started: The migration has been created but not yet run.
   2. In Progress: The migration is partially complete. You can select Resume step to continue the setup wizard, or Update Migration to edit the migration name or description.
   3. Migrated: The migration is complete. You can select View Migration to review the information and resources created during the process, or Update Migration to edit the migration details.

Frequently Asked Questions

This section answers common questions about how Projects Migration creates repositories.

Related Topics

• Projects Migration Best Practices
• Create a Project