Migration phases
Phase 2: Discovery and migration planning
In this phase, your team should run a series of structured discovery workshops to define the foundational elements of the target solution architecture. The goal is to clarify and align on key components early, creating a strong base for the detailed design that follows.
Recommended workshop focus areas
- Core architectural goals and principles
- Key functional and non-functional requirements
- Integration points and system boundaries
- Initial technology choices and constraints
- Risks and assumptions
These workshops should be collaborative, cross-functional, and outcome-driven—prioritizing shared understanding and documented outputs.
Following the establishment of these foundations, a second series of workshops will dive deeper into specific areas such as security, policy frameworks, compliance requirements, and other critical components. Focus and priority of these additional sessions will be directly informed by the outcomes and insights gathered during the initial workshops.
Key insights and decisions from these sessions should be captured in a simple Solution Outline. Once everyone's had a chance to review and agree, this document becomes a clear reference point for the solution's architecture, keeping everyone aligned.
The duration, complexity, and overall success of the migration phase will be significantly influenced by several key business and technical considerations, including:
- Repository structure. How code, artifacts, and packages are organized across repositories.
- Access management. Strategies for managing user identities, roles, and permissions.
- CI/CD pipelines. The design and integration of continuous integration and deployment workflows.
- Repository and organizational structure. Alignment of the repository setup with the broader organizational framework to support scalability, governance, and collaboration.
Proactive attention to these areas during the discovery phase will enable a smooth and efficient migration.
Repository structure
Repository structure shapes the rest of the migration. Most existing platforms organize artifacts as nested folders by project, team, component, or version, or a combination of those, which takes effort to maintain.
The structure helps you, as a DevOps or Platform team, manage artifacts. But not just that; it determines how and who you grant access, what privileges they have, what policies and controls you put in place, and most importantly, determines the location where your developers (and pipelines) can point to pull packages.
For your migration to Cloudsmith, our team can help you decide whether you need one or more of the below Cloudsmith repository structures:
- Super Repository / Mono Repository
- Language-Specific Repositories
- Service/Product/Team Repositories
- Environment-based Repositories
- Hybrid Approaches
See Repositories and Create a repository for how these are set up in Cloudsmith.
At Cloudsmith, you benefit from flat-structure, format-agnostic repositories. Meaning you can start organizing your artifacts in more meaningful, logical ways.
| Repository structure | Why use it? | Why not? |
|---|---|---|
| Super repository | Simplicity of setup Centralization | Limited isolation Lack of fine-grained controls Reduced flexibility |
| Language-specific repositories | Clear organization Isolation of package types Familiarity with other artifact managers | Greater number of repositories Less centralized, with lower visibility of usage, licenses, vulnerabilities, and logs |
| Service, product, or team repositories | Self-serve ownership Granular access control Multiformat flexibility Better visibility | More repositories Some possible package duplication |
| Environment-based repositories | Suits teams automating promotion between environments, such as development, staging, and production | Adds some complexity to package promotion |
| Hybrid approaches | Combines environment-based repositories with service, product, or team repositories | Inherits the trade-offs of both |
Access management
Cloudsmith offers robust and flexible access management features to control exactly who can access your repositories and how. You can manage access at both the individual and team level, assign global or repository-specific privileges, and enforce usage policies such as End User License Agreements (EULAs) for package downloads. For automation and integration purposes, Service Accounts can be configured with fine-grained permissions to ensure secure CI/CD operations.
For enhanced security and enterprise readiness, Cloudsmith supports Single Sign-On (SSO) via SAML, including Group Mapping to streamline user provisioning and role assignment. You can also implement geo or IP-based restrictions to further control who can access your packages and from where. If you're distributing software to external partners or customers, Entitlement tokens offer a secure and scalable way to manage third-party access without compromising internal controls. Whether you're a startup or an enterprise, Cloudsmith provides the access control capabilities you need to maintain security, compliance, and operational efficiency.
CI/CD and pipelines
Understanding and aligning your CI/CD pipelines with your migration strategy is a big part of the migration process. Keep an eye on technical continuity, so you can maintain continuous delivery during the transition. Pipeline integrations are more than just mechanical tasks; they're foundational touchpoints where development, security, and operations intersect.
During the discovery workshops, the Cloudsmith team can help you evaluate your current CI/CD setup to identify where and how Cloudsmith can plug in most effectively. This involves mapping out how your build systems (CI) publish artifacts and how your deployment systems (CD) consume them. For GitHub Actions, Jenkins, GitLab CI, or many other popular tools, Cloudsmith integrates through secure, token-based automation and native support for common package formats.
Beyond compatibility, we must also anticipate change. Cloudsmith encourages pipeline reconfiguration that embraces automation, promotes environment-based release management, and leverages service accounts and API-driven publishing to create resilient, repeatable flows. By aligning your CI/CD pipelines early in the discovery process, you de-risk the migration and build the operational readiness necessary for scale, traceability, and future innovation.
Repo and org structure
When talking about repository structure, Cloudsmith uses three clearly defined categories:
- Multiformat repositories: Cloudsmith supports storing multiple package types and container images in the same repository while still providing support for the native package management tooling for each format.
- Upstream sources: Cloudsmith repos unify local packages and packages sourced from remote repos. Requests for packages that are not present in the repository will be served from an upstream source. Packages can be proxied, or cached for subsequent requests. Upstreams can be configured for resolution priority. Packages fetched from upstreams are tagged.
- Public or private repositories: Cloudsmith supports Public Repositories for anonymous access and Private Repositories with multiple options for authentication. See Repository settings.
Additional configuration considerations
As you migrate your packages and begin setting up Cloudsmith for the first time, there are several key configuration tasks to consider to ensure a smooth and fully functional setup.
First, you'll need to update your build tools and dependency managers to point to your new Cloudsmith endpoints. This often involves modifying configuration files for each package format across your codebase – Cloudsmith provides comprehensive setup guides for all supported formats to help with this. Additionally, configuring upstreams will enable Cloudsmith to fetch and cache third-party dependencies from public sources such as NuGet Gallery, RubyGems.org, or Maven Central, ensuring continuity for your builds.
To round out your setup, consider enabling optional but valuable features like exporting logs to S3 for auditability, configuring signing keys for package authenticity, and setting up custom domains to distribute packages under your own brand. These steps help reinforce best practices around security, traceability, and user experience as you transition to Cloudsmith.
Phase 2 completion: clarity on the migration path
Phase 2 ends with a shared, validated understanding of both your current and target states. The Solution Outline documents the existing architecture, the Cloudsmith-based solution that replaces it, and the decisions that shape the migration. A formal review and sign-off confirms technical integrity, feasibility, and future scalability, which reduces downstream risk and rework.
The Migration and Rollout Strategy turns that solution into a plan. It defines the structure of artifact migration, CI/CD integration, rollout groupings, and the high-level rollout schedule, so the transition is phased and predictable. Together, these two deliverables form the blueprint for execution.
Next steps
With the Solution Outline and the Migration and Rollout Strategy agreed, continue to Phase 3: Migrating your artifacts.
