SonarQube Server to SonarQube Cloud migration plan

The following details will help guide you through migrating from SonarQube Server to SonarQube Cloud.

Pre-requisites

  • A SonarQube Server instance with admin access to migrate from 
  • An account and organization set up in SonarQube Cloud to migrate to
  • Access to your cloud DevOps platform (can be one or more)

Resources

What can be migrated

The following can be migrated from SonarQube Server to SonarQube Cloud using the provided tools.

What can be migrated using the sonar-migration-tool:

  • Projects: Creation of project entities 

 Note: These projects will initially be empty of code and analysis data.

  • Project settings: Configurations specific to each project
  • Quality gates & quality profiles: Creation, assignment, and setting of default quality gates and profiles
  • Groups & permissions: Creation of user groups and their associated permissions
  • Permission templates: Establish templates for permissions
  • Portfolios: Creation of portfolios
  • Project portfolio assignments: Projects assigned to their respective portfolios

After your initial scan on SonarQube Cloud, you can use the sonar-findings-sync to migrate the following issue-related data for each project:

  • Change of issue type (only for Standard Experience)
  • Issue marked as False Positive or Accepted (or Won't Fix from older SonarQube Server instances)
  • Issue re-opened
  • Issue assignments
  • Issue comments
  • Hotspot status changes (Safe, Acknowledged, Fixed)
  • Hotspots re-opened as To Review
  • Hotspot assignments
  • Hotspot comments
  • Custom tags added to issues

Known Limitation: Issue severity can’t be changed when the target is SonarQube Cloud

What can NOT be migrated 

Everything other than what was explicitly stated above can not be migrated and must be manually (re)configured.

The following are some important considerations that require manual action or separate process:

  • Analysis data: Analysis data is not migrated and will show up in SonarQube Cloud after the first scan is run post-migration. It’s important to note that SonarQube Cloud includes auto-analysis, so the first analysis happens automatically.
  • Historical issue data: Issue history is not migrated, however, the sonar-findings-sync tool synchronizes current issue states from SonarQube Server after a new scan has populated analysis data in SonarQube Cloud.
  • Users: User accounts are not migrated. Users will need to be invited or provisioned on SonarQube Cloud.
  • DevOps integrations and CI/CD pipeline configurations: Existing DevOps integrations and configurations of CI/CD pipelines in SonarQube Server must be manually reconfigured for SonarQube Cloud, including URLs, organization keys, and new authentication tokens.

Sample migration plan

Migration team & responsibilities

Role

Responsibility

Specific personnel/team

Project Lead

Overall migration oversight, coordination, communication with stakeholders, user management planning, validation.

Email here

Infra Team

SonarQube Cloud setup, DevOps platform and CI/CD pipeline updates, tool preparation and execution, server decommissioning.

Email here

Dev Teams

Triggering initial scans, verifying project analysis on SonarQube Cloud, using sonar-findings-sync (or assisting a central team).

Email here

SonarQube CSA (Customer Success Architect)

Providing expert guidance, support with tool usage, plan refinement, best practices.

Email here

[other stakeholders]

(e.g., Security Team, QA Team) - For consultation and validation as needed.

Email here

Migration phases, steps & detailed plan

Perform the overall plan in two different phases, one for testing, and one for production.

Phase 1 : Testing

  • Run through all of the Steps 1-6 (excluding Step 7) below
  • Use a SonarQube Server test instance and a sandbox in SonarQube Cloud
  • Performed to simulate the actual production run, but in a controlled environment
  • Get feedback from this run, and then refine the plan based on findings

Phase 2 : Production

  • Run through all of the Steps below
  • Performed in Production

Steps for each phase:

Step 1: Preparation & planning

Task 1.1: Initial Scoping & Assessment 

DRI: Project Lead, with guidance from SonarQube CSA

  • Identify all projects for migration. Compile a list
  • Document current SonarQube Server version, database size, and any critical custom configurations (plugins, rules)
  • Review current quality profiles and quality gates; identify any that can be standardized or retired
  • Map existing user groups and their permissions
  • List all CI/CD pipelines integrated with SonarQube Server
  • Output - “Initial Scoping Doc”

Task 1.2: SonarQube Cloud organization setup

DRI: Project Lead, Infra Team

  • Create/confirm SonarQube Cloud organization
  • Note the SonarQube Cloud organization key
  • Configure organization-level settings: Authentication (e.g., GitHub, Azure DevOps, SAML), Billing, Security

Task 1.3: Tool familiarization & installation

DRI: Infra Team,  with guidance from SonarQube CSA

  • Thoroughly review documentation for sonar-solutions/sonar-reports and sonar-findings-sync
  • Select 1-3 non-critical projects for a sandbox migration

Task 1.4: Develop communication plan

DRI: Project Lead

  • Identify all stakeholders (dev teams, management, security, etc.
  • Outline communication channels (e.g., email etc), frequency, and key messages for each phase
  • Plan how users will be created/invited to SonarQube Cloud
  • Prepare user communication for SonarQube Cloud access and usage

Step 2: Pre-migration configuration

Task 2.1: Prepare sonar-solutions/sonar-reports tool 

DRI: Infra Team, with guidance from SonarQube CSA

  • Clone the repository, install prerequisites
  • Configure the tool with SonarQube Server and SonarQube Cloud API endpoints, tokens, and organization key
  • Test connectivity

Step 3: Execution - project structure & configuration migration

Task 3.1: Execute sonar-solutions/sonar-reports tool

DRI: Infra Team, with guidance from SonarQube CSA

  • Run the scripts to migrate projects, settings, quality profiles quality gates, groups, permissions, and portfolios
  • Monitor tool output for any errors or warnings

Task 3.2: Verify project structure migration

DRI: Project Lead, with  guidance from SonarQube CSA

  • Log in to SonarQube Cloud and spot-check a selection of projects to confirm they exist with correct settings
  • Compare counts of projects, groups, portfolios between server and cloud

Step 4: CI/CD pipeline updates & first scans 

Task 4.1: Update main CI/CD pipeline script(s)

DRI: Infra Team

  • Modify scripts to change the server URL to https://sonarcloud.io
  • Include the SonarQube Cloud organization key (sonar.organization)
  • Update the SONAR_TOKEN or authentication method
  • Test the updated pipeline configuration on a pilot project

Task 4.2: Communicate CI/CD changes to development teams

DRI: Project Lead

Task 4.3: Trigger initial scans for migrated projects 

DRI: Dev Teams, Infra Team

  • As projects are built, analysis reports will be sent to SonarQube Cloud
  • Monitor SonarQube Cloud to see projects being populated with scan data

Step 5: Issue data synchronization (post-initial scan)

Task 5.1: Prepare sonar-findings-sync

DRI: Infra Team, with guidance from SonarQube CSA

  • Clone the repository and prepare configuration for the tool

Task 5.2: Run sonar-findings-sync for each project in SonarQube Server

DRI: Dev Teams

  • Important: This step must be performed after a project has had its first successful scan on SonarQube Cloud
  • Execute the script to synchronize issue statuses, assignments, comments, and hotspot data

Task 5.3: Verify issue synchronization

DRI: Dev Teams, Project Lead

  • For a sample of issues, verify that statuses and comments match between your SonarQube Server instance and SonarQube Cloud

Step 6: Validation & cutover

Task 6.1: Final validation

DRI: Project Lead, Dev Teams, with guidance from SonarQube CSA

  • Confirm all targeted projects are consistently reporting to SonarQube Cloud
  • Ensure users have the necessary access

Task 6.2: Communicate official switch to SonarQube Cloud

DRI: Project Lead

  • Announce the official cutover to SonarQube Cloud

Task 6.3: Decommission SonarQube Server

DRI: Infra Team

  • After a stability period (e.g., 2-4 weeks), perform a final backup and shut down the server

Step 7: Ongoing post-migration support & optimization

Task 7.1: Monitor SonarQube Cloud performance and usage

DRI: Project Lead,  with guidance from SonarQube CSA

Task 7.2: Introduction to SonarQube Support

DRI: Project Lead,  with guidance from SonarQube CSA

  • Introduce SonarQube Cloud Support Team
  • Run through how-to usage of SonarQube Zendesk Service-desk UI

Task 7.3: Optimize SonarQube Cloud configuration on an ad-hoc basis

DRI: Project Lead, with guidance from SonarQube CSA

Key considerations & limitations for the migration

  • Code & full issue history: Understand that code and the complete, historical timeline of issues populate SonarQube Cloud after the first new scan. The sonar-findings-sync tool is crucial for reconciling the current state of issues.
  • User migration: User accounts require manual setup on SonarQube Cloud.
  • CI/CD updates are critical: This is the most significant manual effort and requires careful planning and execution by your Infra Team.
  • Downtime/freeze: A "read-only" or "freeze" period on the old SonarQube Server is advisable before running the migration tools to ensure consistency.
  • Rollback plan: The primary rollback mechanism is reverting CI/CD pipeline changes to point back to the SonarQube Server. Keep the server running in read-only mode for a defined period post-migration.

Timeline overview

A detailed timeline and task tracking sheet can be maintained in a shared document: 

  • Step 1 (preparation & planning): [start date] - [end date]
  • Step 2 (pre-migration configuration): [start date] - [end date]
  • Step 3 (project structure migration): [start date] - [end date]
  • Step 4 (CI/CD updates & first analysis): [start date] - [end date] (rolling basis)
  • Step 5 (issue data synchronization): [start date] - [end date] (rolling basis, post-scan)
  • Step 6 (validation & cutover): [start date] - [end date]
  • Step 7 (post-migration support): ongoing & ad-hoc

Communication plan

Audience

Key information

Channel(s)

Frequency

Owner

Executive Sponsors

Migration progress, key milestones, risks, go/no-go for cutover.

Email updates, Steering Committee meetings

Bi-weekly, Ad-hoc

Project Lead

Development Teams

Timeline, impact on workflows, CI/CD changes, SonarQube Cloud access & training.

Email, Team meetings, Wiki/Confluence page

Weekly, As needed

Project Lead

Infrastructure Team

Technical tasks, dependencies, schedule for tool execution and CI/CD updates.

Daily stand-ups (during execution), Team meetings

Daily/Weekly

Project Lead

All Users

Upcoming changes, SonarQube Cloud introduction, support channels.

Email, Intranet announcements

Milestone-based

Project Lead

This plan provides a comprehensive framework. It should be reviewed and adapted to your specific environment and requirements. Regular communication and collaboration between all parties will be key to a successful migration.