We are excited to announce the launch of the Sonar Migration Tool, a new, purpose-built utility that makes migrating from SonarQube Server to SonarQube Cloud faster, more reliable, and accessible to every team, regardless of the size or complexity of their setup.
What problems does the Sonar Migration Tool solve?
Migrating from SonarQube Server to SonarQube Cloud has historically been a significant, manual, and error-prone undertaking. Earlier tools were side projects, not well documented, limited in scope, and required hands-on assistance from Sonar technical staff. Customers with complex environments had no clear, repeatable path.
Over the past year, two internal efforts were made to build a production-grade tool to automate the migration of customer data from SonarQube Server to SonarQube Cloud. The result is the Sonar Migration Tool: a robust, fully documented, and designed from the ground up with self-service in mind.
What does the Sonar Migration Tool do?
The Sonar Migration Tool automates the end-to-end migration of a SonarQube Server instance to SonarQube Cloud Enterprise.
It migrates:
- Projects, with all their settings, webhooks, links, and new code period configuration
- Quality Gates and Quality Profiles, including custom rules and parent relationships
- Groups, Permissions, and Permission Templates
- Portfolios (Enterprise edition)
- Issue and Security Hotspot history, statuses, comments, tags, and triage decisions are preserved
- Source code and metrics, so your projects on SonarQube Cloud are seeded immediately, no immediate re-scan required
- All branches, non-main branches migrate as long-lived branches with their full issue history intact
- Issue creation dates:, preserved via backdating, so your new-code-period baseline remains accurate from day one
How do you run the Sonar Migration Tool step by step?
For teams with a straightforward setup, one SonarQube Server instance feeding a single SonarQube Cloud organization, migration now takes four commands and a config file.
sonar-migration-tool extract --config my-config.json
sonar-migration-tool structure --config my-config.json
sonar-migration-tool mappings --config my-config.json
sonar-migration-tool migrate --config my-config.json \
--default_organization <someOrg>The config file itself is minimal, just your SonarQube Server URL and token, and your SonarQube Cloud token and enterprise key.
For even simpler cases, such as migrating a single project or a small known set of projects, the transfer command chains all four phases into one.
sonar-migration-tool transfer \
--source_url https://sonarqube.example.com \
--source_token squ_xxx \
--project_key <myProjectKey> \
--target_token squ_xxx \
--default_organization <someOrg>One command. Done.
For teams who prefer not to type commands at all, a browser-based GUI is also available.
The GUI is currently experimental in the first release, but will be fully supported in a coming release.
sonar-migration-tool gui --config my-config.json This opens a guided migration interface in your default browser with progress bars, an event log, and visual CSV editors.
Customers can run it themselves
One of the core design objectives of the Sonar Migration Tool is self-service. For customers with a simple setup, such as a single SonarQube Server instance and a single SonarQube Cloud organization, no technical assistance from Sonar is needed. Download the binary, prepare a config file, run four commands.
The tool ships as a single static binary with no installer, no runtime dependencies, and no database. It runs on macOS, Linux, and Windows (X64 and ARM64). There is nothing to install beyond downloading and making it executable.
For more complex migrations, like multiple SonarQube Server instances, multiple target organizations, or environments requiring careful review of the mapping between DevOps platforms and SonarQube Cloud organizations, the multi-phase workflow gives full control over each step. It also includes the ability to review and edit intermediate CSV files before committing to the migration in order to plan your migration.
How fast is it?
Migration speed depends on a number of factors: the number of projects, total lines of code, branch count, the number of issues with manual triage, and network latency. As a general reference point, the tool has been benchmarked against a representative small platform: 70 projects, 100 branches, 500K lines of code, and 1,000 issues with manual changes. Performance figures for this configuration are available in the quick-start guide.
For large instances (50,000+ projects), concurrency and timeout settings can be tuned, and the tool's resume capability ensures that a failure (OOM, network disconnection…) at any point does not require restarting from scratch.
Which SonarQube Server versions are supported by the Sonar Migration Tool?
The Sonar Migration Tool is compatible with:
- All editions of SonarQube Server: Developer, Enterprise, and Data Center and even SonarQube Community Build
- All LTA versions from SonarQube Server 9.9 and above (intermediate versions are likely to work but have not been formally validated)
- All Active SonarQube Server versions at any given moment (currently 2026.3 and 2026.4 as of Aug 1st, 2026)
Authentication is version-aware: Basic auth is used for SonarQube Server versions below 10, and Bearer token for version 10 and above.
What are the prerequisites for migrating to SonarQube Cloud?
Before running the tool, you will need:
- A SonarQube Cloud Enterprise account with the target organizations already created
- Admin access to your SonarQube Server or Community Build instance (System Admin token)
- A SonarQube Cloud admin token with enterprise-level permissions
- A machine with at least 8 GB of RAM (the tool itself uses around 3 GB)
- Local disk space equal to at least 5× the size of your SonarQube Server database (the extracted data is stored locally before being pushed to the cloud)
Installation is a single step: download the binary for your operating system from the releases page, extract the archive, and make it executable.
mv sonar-migration-tool-<OS>-<ARCH> sonar-migration-tool
chmod +x sonar-migration-tool
./sonar-migration-tool --help No Go installation, no package manager, no configuration files required to get started.
Detailed migration reporting
One of the most important capabilities of the Sonar Migration Tool is its migration report. Because SonarQube Server and SonarQube Cloud are not feature-identical, a migration is rarely 100% perfect, and the tool is transparent about this.
After every migration run, a report is generated in both PDF and Markdown formats (migration_summary.pdf / migration_summary.md). Every migrated object is classified as:
- Perfect — migrated with 100% fidelity
- Near Perfect — migrated with minor, acceptable loss of fidelity
- Partial — migrated with significant loss of fidelity (with explanation)
- Failed — an error occurred during migration (with detail)
- Skipped — not migrated, either by configuration or because the concept does not exist in SonarQube Cloud
The report explains why each non-perfect result occurred. Common reasons include: Quality Gates using metrics that don't exist in SonarQube Cloud, Quality Profiles with rules from third-party plugins, permissions granted to individual users (SonarQube Cloud manages identity through an IdP), or projects using a reference branch as their new code period.
Before running the actual migration, teams can generate a predictive report using only the output extract, no SonarQube Cloud credentials required. This makes it possible to review expected results in advance, including sending the output extract to Sonar's technical team for a pre-migration review.
What are the limitations of migrating from SonarQube Server to SonarQube Cloud?
The tool migrates everything it can, but some aspects of a SonarQube Server configuration have no equivalent in SonarQube Cloud or require manual steps post-migration:
- Project analysis history is not migrated, only the latest analysis state is preserved
- User accounts and authentication are not migrated, identity management in SonarQube Cloud is handled by your identity provider and must be configured separately
- Permissions granted to individual users (as opposed to groups) are not migrated.
- Applications are not migrated
- Portfolio hierarchies are not migrated (flat portfolios are)
- Issue assignments are not preserved
- SCM blame data is attributed to a generic
sonar-migration-toolcommitter, this resolves itself after the first real scan on SonarQube Cloud - CI/CD pipeline configuration must be updated manually (change
SONAR_HOST_URLandSONAR_TOKENin your pipelines)
Post-migration activities
Once the migration tool completes successfully, a few manual steps are needed to finish the transition:
- Verify in SonarQube Cloud: confirm projects appear under the target organization, spot-check quality gates and profiles, and verify issue history and branches
- Bind projects to DevOps platforms: repository bindings (GitHub, GitLab, Azure DevOps, Bitbucket) are not migrated and must be configured in SonarQube Cloud
- Update CI/CD pipelines: point your pipelines at SonarQube Cloud by updating
SONAR_HOST_URLandSONAR_TOKEN - Re-scan your projects: run a normal analysis from your CI pipelines to confirm everything works end to end on the new platform
- Migrate other integrations: IDE Connected Mode settings, email notifications, and any custom API integrations or provisioning scripts will need to be reconfigured for SonarQube Cloud
- Decommission your SonarQube Server instance once you are satisfied with the migration
For complex environments, Sonar's Solutions Engineering and Onboarding teams can assist with a structured four-phase engagement: discovery and planning, migration strategy definition, migration execution, and post-migration validation.
The time to move to SonarQube Cloud is now
SonarQube Cloud is where Sonar's investment in clean code analysis, AI-assisted remediation, and developer experience is most concentrated. With the launch of the Sonar Migration Tool, the last significant barrier to migration, the effort and risk of the move itself, has been removed.
Whether your team wants to run the migration independently over a weekend or work with Sonar's technical team on a structured project, the path is now clear, automated, and transparent.
Get started with the Sonar Migration Tool →
The Sonar Migration Tool is available now. Download the binary for your platform from the releases page and follow the quick-start guide to begin your migration to SonarQube Cloud.