Migration phases
Phase 3: Migrating your artifacts
This phase moves your artifacts from your existing solution to Cloudsmith while build artifacts stay available to your developer teams. Most migrations combine two of the strategies below: new builds start publishing to Cloudsmith straight away, and existing artifacts follow either on demand or in bulk.
Choose a route
Start from the size of the job and whether Cloudsmith can reach your existing platform over the internet. The Cloudsmith team helps you choose, and runs the bulk transfer for you where that is the better route.
| Your situation | Recommended route | What to read |
|---|---|---|
| Artifactory, more than a handful of repositories, or more than a few hundred gigabytes | Publish new builds to Cloudsmith now. Let the Cloudsmith team run the bulk transfer with an admin token. | Bulk migration run by the Cloudsmith team |
| Your platform is reachable from the internet and your security team will permit the connection | Publish new builds to Cloudsmith now. Configure the old platform as an upstream so existing artifacts migrate as teams request them. Bulk import whatever is left at the end. | Just-in-time, Configuring legacy platforms as upstreams |
| Your platform is not reachable, or the connection is not approved | Publish new builds to Cloudsmith now. Export hosted repositories and import them with the CLI, one repository at a time. | Back-filling, Running a bulk import |
| Release pipelines cannot change yet | Publish to Cloudsmith and let the old platform proxy Cloudsmith until the pipelines cut over. | Registry proxy migration |
| Mostly container images | Copy them registry to registry. No export, no local disk. Do this first regardless of route. | Importing Docker images |
Whatever the route, only hosted repositories hold artifacts that need moving. Proxy and virtual repositories are configuration and are recreated as Cloudsmith upstreams. See Migrating artifacts from JFrog Artifactory or Migrating artifacts from Sonatype Nexus for the mapping.
What does and does not carry across
Set expectations with stakeholders before the first package moves. Packages and their contents migrate intact. Most of what surrounds them does not.
| Outcome | |
|---|---|
| Package files, names, versions | Migrate intact. Cloudsmith reads them from the package itself. |
| Checksums | Unchanged. The bytes are the same. |
| Container image digests | Preserved by registry-to-registry copy. Changed by docker save and upload. |
| Maven snapshot timestamps | Re-assigned on upload. 1.0-SNAPSHOT keeps resolving; builds pinned to a timestamp need updating. |
| Upload date, uploader, download counts | Reset. Every package shows the migration account and date. Use tags to record where a package came from. |
| Repository signing | Cloudsmith signs repositories with its own key, or a custom key you supply. Consumers trust the new key. |
| Properties, attributes, and other platform-specific metadata | Not transferred. Cloudsmith has custom metadata if you want to carry it, but the migration scripts do not. |
| Users, groups, permissions | Recreated in Cloudsmith, usually through SSO, as planned in Phase 2. |
| Proxy, remote, virtual, and group repositories | Recreated as upstreams. Nothing to export. |
| Build info, plugins, replication, and other platform features | Not migrated. |
| Duplicate files in the source | Collapse into one package in Cloudsmith unless overwrites are enabled. |
The four strategies
Front-filling
Also called dual-publishing, front-filling publishes every new build to both platforms. In practice it is
one more publish step in CI: a second cloudsmith push, docker push, or mvn deploy target alongside the
existing one. Nothing existing moves, but from day one every new artifact is in Cloudsmith, and teams can
start consuming from it. Almost every migration begins this way.
Back-filling
Back-filling moves existing artifacts out of the old platform in bulk. Export a hosted repository, push it into Cloudsmith with the CLI, verify the counts, move on to the next. It is the only route when Cloudsmith cannot reach your platform, and the route for anything just-in-time never picked up. Running a bulk import is the runbook.
Just-in-time
Just-in-time configures the old platform as a Cloudsmith upstream in Cache and Proxy mode. Teams point their tooling at Cloudsmith; anything not yet present is fetched from the old platform and stored. Frequently used artifacts migrate themselves within days, and what nobody requests was not worth moving. It needs an internet-reachable platform and your security team's approval for outbound requests from Cloudsmith, which is typically the longest lead time in the whole migration. See Configuring legacy platforms as upstreams.
Registry proxy migration
Registry proxy migration is the inverse of front-filling: builds publish to Cloudsmith, and the old platform is given Cloudsmith as a remote or proxy repository so release pipelines that cannot change yet keep pulling through it. As pipelines cut over, the old platform serves less until it is only a passthrough and can be switched off. Common with Nexus, where a proxy repository pointed at Cloudsmith takes a few minutes to set up.
Note
Just-in-time and registry proxy migration both need a live connection between the platforms. Where that is not possible, use the upstream proxy agent for the just-in-time case, or fall back to back-filling.
Importing it yourself
If you are running the import rather than handing it to the Cloudsmith team, three pages cover the work:
- Running a bulk import is the runbook: the order to take repositories in, the service account, tags, rate limits, and how to verify each one before moving to the next.
- Importing packages with the CLI has the scripts, with a section for single-file formats, Maven, Debian and RPM, and raw files.
- Importing Docker images copies container images registry to registry.
Cloudsmith provides setup guides for all supported formats.
Phase 3 completion: migration is underway
Build pipelines publish to Cloudsmith directly, so new artifacts are available for development and deployment straight away. Existing artifacts are arriving either on demand through upstreams or in bulk, repository by repository, with counts verified as each one lands. Upstreams or proxy configurations keep downstream systems supplied while that happens.
Next steps
Once your artifacts are flowing into Cloudsmith, continue to Phase 4: Validation and decommissioning.
