Projects Migration Best Practices

Projects are the essential enabler for enterprise scale: they are logical management entities that adapt to your specific organizational DNA, mapping perfectly to an application, a team, a microservice, or even an external GitHub organization. Projects provide clear operational governance, resource ownership, and cost accountability for a defined scope, allowing you to grow efficiently across teams and use cases.

Why Use Projects?

Projects offer the following benefits:

• Managed Scalability: Projects provide the logical workspace to govern Artifactory resources and users at scale, moving to mapping based on your business DNA.
• Separation of Concerns: Enable strict resource isolation and granular RBAC, ensuring that compliance and security are maintained even as the organization grows.
• Delegated Authority: Empower developers through self-service administration, removing the platform admin bottleneck by allowing project admins to manage their own teams
• Optimized Efficiency: Context-aware management allows for virtual repositories and storage quotas tailored to specific technologies, teams, or lifecycle stages.

Different Migration Scenarios

Migrating to projects has different focus points according to your existing organizational structure.

Migration from Monorepo

In this scenario, you have a single ‘mega-repo’, a massive monolithic Git repository that handles all organizational traffic.

• Goal: Break down the monolithic structure into logical, project-based boundaries.
• Focus: Decouple repositories and resolve performance bottlenecks caused by excessive metadata and asset scaling.

Migration from Global Permission Tiers

In this scenario, commonly found in many legacy setups, you manage access by using technology-wide repositories for each major tier of your CI (DEV / QA / PROD). For example, you may have one docker-dev JFrog repository used by dozens of teams rather than organizing by project.

• Goal: Shift from stage-based ownership managed by Platform Admins to project-based ownership managed by Project Admins.
• Focus: Improve security isolation and governance. Instead of a single shared development repository, each team manages its own development, testing, and production repositories within its project scope. This architecture enables team-specific retention policies and prevents cross-talk between different products.

The table below shows the differences in migrating from common structures (from monorepos or global permission tiers):

How to Migrate to Projects

Every organization’s migration to projects is different, but the migration process itself follows the same steps, which create a modernized environment with granular, scalable permissions:

• Step 1: Create the Access Model
• Step 2: Set Up the Repository Structure
• Step 3: Bridge Legacy Data
• Step 4: CI/CD Shift

Step 1: Create the Access Model

Set the foundations for your new structure by creating the projects and creating roles and access rules for them.

1. Decide how you want to divide projects in your environment and create the projects

   📘

   Tip

   A project = team division is recommended for most use cases, as it ensures consistent organization and simplifies tracking artifact ownership.

2. Create project roles

3. Assign members and map existing user groups to the new project roles (for example: Developer, CI, Project Admin)

4. Configure OpenID Connect integration, the recommended authentication method

5. Group Mapping: Map existing user groups to the new Project Roles (Developer, CI, Project Admin).

6. The "External Stage" Pattern: Set up an external stage (formerly Environment), a shared space for general-use resources, which allows you to give developers write access to the remote cache to download new packages from the internet, but keep them as read-only on Dev and Prod stages. This prevents manual uploads to internal environments while allowing development to flow.
   To set up the pattern:

   1. Create a stage for remote/ third-party repositories
   2. Assign the repositories to the stage
   3. Share the repositories with all relevant projects

Step 2: Set Up the Repository Structure

Establish a repository structure inside each project to manage its resources.

1. Per-stage locals: Create local repositories for each technology per stage of the project (for example, maven-dev-local, maven-prod-local).

2. The virtual wrapper: Create a virtual repository, that aggregates all locals and remotes. This will be the single-URL access for developers and CI.

   📘

   Tip

   Order matters in virtual repositories: for faster resolution for stable assets, select the Prod local repository first.

Step 3: Bridge Legacy Data

Establishing a transition path from the old Monorepo to the new project environment is a critical step. We suggest evaluating these three implementation paths, categorized by their balance of administrative oversight and migration velocity.

There are three methods to do this:

• Shared Repository (the “Speed” Approach)
• Smart Remote Repository (the "Balanced" Approach)
• Legacy Local/ Manual Migration (the "Clean Break" Approach)

Shared Repository (the “Speed” Approach)

This is the quickest solution, where you keep the existing global monorepo and share it with the new projects as read-only. Then, add it to the projects’ virtual repositories.

Smart Remote Repository (the "Balanced" Approach)

This solution balances ease of application with a scalable solution: in it, you create a Smart Remote repository inside the Project that points to the global monorepo. The Smart Remote repository acts as a filter, as it only caches in the project the assets that were actually requested.

Legacy Local/ Manual Migration (the "Clean Break" Approach)

This is the most operationally heavy solution, which creates the most optimized result. In it, you create a dedicated local repository (e.g., legacy-local) in the project and manually copy only the specific required assets from the monorepo.

Step 4: CI/CD Shift

After creating the structure and legacy data plan, it is time to transition your organization. This is the most intensive part of the modernization process: we recommend conducting it gradually to validate the new project-based workflows without disrupting the existing operations.

Transitioning the logic of your delivery pipeline is the most intensive part of the modernization journey. To maintain stability, we recommend a "Parallel Execution" or "Shadow" approach, ensuring that new project-based workflows are validated without disrupting the existing monorepo operations.

• Shadow method: Test the new workflows behind the scenes without touching live operations.
• Parallel execution method: Run old and new workflows side by side, gradually shifting real operations to the new system.”

To complete the execution phase, follow these steps:

1. Modernize Your Pipeline
2. Make Technology-Specific Code Adjustments
3. Ensure Developer Enablement and Workstation Alignment
4. Scale with Automation
5. Decommission the Legacy Environment

1. Modernize Your Pipeline

The complexity of this step scales with your current implementation. We suggest prioritizing the following technical updates:

• Authentication & Identity: Transition from global credentials to OIDC (OpenID Connect) or project-level access tokens. This establishes a secure, scoped identity for each pipeline.
• URL & Command Refactoring: Update all download and upload URLs to point to the new project virtual repositories. This includes modifying JFrog CLI commands to include the --project flag or specific project-scoped paths.
• To assess your Implementation:
  • Centralized Environments: If you utilize reusable workflows or shared libraries, apply changes at the library level to propagate updates across multiple repositories simultaneously.
  • Standalone Environments: For decentralized setups, expect a higher effort per repository to manually refactor individual pipeline files.

2. Make Technology-Specific Code Adjustments

Beyond your pipeline scripts, certain technologies require internal configuration changes to recognize the new project boundaries:

• Maven: Update the \<distributionManagement> and \<repositories> sections in the pom.xml file to point to the project-specific virtual repositories.
• Docker: Update the FROM instructions in your Dockerfiles to pull base images from the new project-scoped registry instead of the global monorepo.

3. Ensure Developer Enablement and Workstation Alignment

A successful transition relies on moving the developers' daily routines into the Project scope.

• Training & Documentation: Use the ‘pilot’/ gradual release phase to create a "migration playbook", which includes training material and workflows. This ensures that subsequent teams can self-serve during their transition.
• Local Configuration: Instruct developers to update their local package manager settings (for example: .npmrc, settings.xml, pip.conf). They should perform a new docker login to the project-specific virtual URL to ensure their local environment mirrors the CI environment.

4. Scale with Automation

As the number of projects grows, operational overhead increases quickly due to the combined scale of technologies, repositories, and projects that must be managed. In practice, the effort grows roughly with the multiplier of [Number of technologies × Number of repositories × Number of projects].

To mitigate this overhead, we recommend using Terraform to manage all project resources (e.g., repositories, permissions, and URLs). By applying an Infrastructure as Code (IaC) approach, teams can ensure consistent configuration, reduce manual management, and spin up new projects in minutes rather than hours.

5. Decommission the Legacy Environment

Once you have successfully validated your new CI/CD lifecycle in the new environment, you are ready to phase out the legacy data. To protect your environment, enact a read-only grace period for the legacy monorepo before final archiving. This acts as a safety net while the organization fully commits to the project-managed environment.

UI and REST API Documentation Quick Reference

Use the following table to find the specific documentation for each part of the setup process.