From 9981e65766e2091c418f9d26824e9c56af955f27 Mon Sep 17 00:00:00 2001 From: Keith E <129207802+kiloecho-sonar@users.noreply.github.com> Date: Thu, 12 Mar 2026 15:45:06 -0500 Subject: [PATCH 1/2] README.md compromise --- README.md | 39 ++++++++++++++++++++++++++++++++++++++- 1 file changed, 38 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index be662985..ff24c677 100644 --- a/README.md +++ b/README.md @@ -53,6 +53,25 @@ A CLI tool for migrating SonarQube Server configurations to SonarQube Cloud. Ext --- +## What Gets Migrated + +| Category | Status | Notes | +|----------|--------|-------| +| Projects | ✅ Migrated | Created and linked to repositories | +| Quality Profiles | ✅ Migrated | Restored from backup, inheritance set, defaults configured | +| Quality Gates | ✅ Migrated | Gates with conditions and default assignments | +| Groups & Permissions | ✅ Migrated | User groups, organization permissions, permission templates | +| Portfolios | ✅ Migrated | Created with project assignments | +| Historical analysis data | ⚠️ Not Migrated | Previous scan history does not transfer | +| Issue history | ⚠️ Not Migrated | Existing issues and comments stay on Server | +| Code coverage history | ⚠️ Not Migrated | Coverage trends reset after re-scan | +| Security hotspot history | ⚠️ Not Migrated | Hotspot review states do not transfer | +| Source code | ⚠️ Not Migrated | Pulled from your repositories directly | + +> **Note**: After migration, re-scan your projects in SonarQube Cloud to populate analysis data. + +--- + ## Getting Started Choose your approach: @@ -63,6 +82,8 @@ Choose your approach: ## Interactive Wizard (Recommended) +> **Recommended for most users. No scripting required.** + For a guided migration experience, use the interactive wizard command. The wizard walks you through each phase, prompting for credentials and providing progress feedback. ### Command @@ -126,7 +147,9 @@ Phase 2 of 7: Structure ## Manual CLI Method -Most users should use the wizard. For scripting or automation, use the manual commands below. +> For scripting, automation, or advanced users who need direct control over each phase. + +> Most users should use the [Interactive Wizard](#interactive-wizard-recommended) instead. ### Step 1: Create a working directory @@ -469,6 +492,20 @@ docker run -v ./files:/app/files ghcr.io/sonar-solutions/sonar-reports:latest \ --- +## Post-Migration Steps + +After the migration completes, verify your SonarQube Cloud environment and prepare for re-analysis: + +1. **Verify projects** — Log in to SonarQube Cloud and confirm all expected projects appear and are linked to their repositories. + +2. **Verify Quality Gates and Profiles** — Check that quality gates have the correct conditions and quality profiles contain the expected rules and are set as defaults where needed. + +3. **Re-scan your projects** — Historical analysis data does not transfer. Trigger a new scan for each project (via CI/CD or manually) to populate analysis results in SonarQube Cloud. + +4. **Configure DevOps integration** — If you ran the Pipelines phase, confirm that CI/CD secrets (`SONAR_TOKEN`, `SONAR_HOST_URL`) are set correctly in your DevOps platform and that pipelines are pointing to SonarQube Cloud. + +--- + ## Output Files Reference ### Extraction Output From 5e90cb31592c47b365170b91ea1c0da42647260c Mon Sep 17 00:00:00 2001 From: Keith E <129207802+kiloecho-sonar@users.noreply.github.com> Date: Thu, 12 Mar 2026 17:53:18 -0500 Subject: [PATCH 2/2] README.md made more succinct. Removed references to the Full Migrate. These executibles are not working as expected and need to be tested further to make functional --- README.md | 152 +++++++++--------------------------------------------- 1 file changed, 24 insertions(+), 128 deletions(-) diff --git a/README.md b/README.md index ff24c677..fcfefce9 100644 --- a/README.md +++ b/README.md @@ -100,18 +100,6 @@ docker run -it -v ./files:/app/files ghcr.io/sonar-solutions/sonar-reports:lates |--------|-------------|---------| | `--export_directory` | Root directory for export files and wizard state | `/app/files/` | -### What the Wizard Does - -The wizard guides you through all migration phases: - -1. **Extract** - Prompts for SonarQube Server URL and admin token, optional client certificate -2. **Structure** - Automatically generates organization and project mappings -3. **Organization Mapping** - Prompts you to map each SonarQube Server org to a SonarQube Cloud org key -4. **Mappings** - Generates entity mappings (gates, profiles, groups, templates) -5. **Validate** - Runs pre-flight validation checks -6. **Migrate** - Confirms before pushing configurations to SonarQube Cloud -7. **Pipelines** - Optional CI/CD pipeline updates (if secrets.json exists) - ### Features - **Resume support**: If interrupted, the wizard saves state and resumes from the last completed phase @@ -119,30 +107,6 @@ The wizard guides you through all migration phases: - **Progress display**: Shows current phase and overall progress - **Validation**: Checks that all organizations are mapped before migration -### Example Session - -``` -$ docker run -it -v ./files:/app/files ghcr.io/sonar-solutions/sonar-reports:latest wizard - -╔════════════════════════════════════════════════════════════════╗ -║ SonarQube Migration Wizard ║ -║ Migrate from SonarQube Server to SonarQube Cloud ║ -╚════════════════════════════════════════════════════════════════╝ - -Phase 1 of 7: Extract -───────────────────── -SonarQube Server URL: https://sonar.example.com -SonarQube Server Admin Token: ******** -Do you need to use a client certificate? [y/N]: n - -Extracting data from SonarQube Server... -✓ Extract complete: 1706745600 - -Phase 2 of 7: Structure -─────────────────────── -... -``` - --- ## Manual CLI Method @@ -158,52 +122,9 @@ mkdir sonar-migration cd sonar-migration ``` -### Step 2: Extract data from SonarQube Server - -```bash -docker run -v ./files:/app/files ghcr.io/sonar-solutions/sonar-reports:latest \ - extract https://your-sonarqube-server.com YOUR_SQS_ADMIN_TOKEN -``` - -### Step 3: Generate organization structure - -```bash -docker run -v ./files:/app/files ghcr.io/sonar-solutions/sonar-reports:latest structure -``` - -### Step 4: Map your SonarQube Cloud organizations - -Open `./files/organizations.csv` and fill in the `sonarcloud_org_key` column with your SonarQube Cloud organization keys: - -```csv -alm,server_url,org_name,sonarcloud_org_key -github,https://your-sonarqube-server.com,my-github-org,my-cloud-org-key -``` - -### Step 5: Generate entity mappings - -```bash -docker run -v ./files:/app/files ghcr.io/sonar-solutions/sonar-reports:latest mappings -``` - -### Step 6: Run the migration - -```bash -docker run -v ./files:/app/files ghcr.io/sonar-solutions/sonar-reports:latest \ - migrate YOUR_SQC_ENTERPRISE_TOKEN your-enterprise-key -``` - -### Step 7: Verify migration - -Log in to your SonarQube Cloud organization and verify: -- Quality Gates were created with correct conditions -- Quality Profiles were restored with rules -- Groups exist with proper permissions -- Projects are linked to repositories - --- -### Phase 1: Extract +### Step 2: Extract data from SonarQube Server Extract configuration data from your SonarQube Server instance via the REST API. @@ -225,11 +146,12 @@ docker run -v ./files:/app/files ghcr.io/sonar-solutions/sonar-reports:latest \ | Option | Description | Default | |--------|-------------|---------| +| `--config` | Path to JSON configuration file (alternative to CLI arguments) | - | | `--export_directory` | Output directory for extracted data | `/app/files/` | | `--concurrency` | Maximum concurrent API requests | 25 | | `--timeout` | Request timeout in seconds | 60 | | `--extract_id` | Resume a previous extraction | (new extraction) | -| `--extract_type` | Type of extraction to run | (full) | +| `--extract_type` | Type of extraction to run | (all) | | `--target_task` | Run only a specific task and its dependencies | (all tasks) | | `--pem_file_path` | Client certificate PEM file (for mTLS) | - | | `--key_file_path` | Client certificate key file (for mTLS) | - | @@ -246,9 +168,7 @@ docker run -v ./files:/app/files ghcr.io/sonar-solutions/sonar-reports:latest \ --- -### Phase 2: Structure - -Generate organization and project mappings based on DevOps platform bindings. +### Step 3: Generate organization structure #### Command @@ -269,7 +189,18 @@ After running `structure`, you must edit `organizations.csv` and fill in the `so --- -### Phase 3: Mappings +### Step 4: Map your SonarQube Cloud organizations + +Open `./files/organizations.csv` and fill in the `sonarcloud_org_key` column with your SonarQube Cloud organization keys: + +```csv +alm,server_url,org_name,sonarcloud_org_key +github,https://your-sonarqube-server.com,my-github-org,my-cloud-org-key +``` + +--- + +### Step 5: Generate entity mappings Create detailed mapping files for all entities that will be migrated. @@ -290,7 +221,7 @@ Outputs `gates.csv`, `profiles.csv`, `groups.csv`, `templates.csv`, and `portfol --- -### Phase 4: Migrate +### Step 6: Run the migration Execute the migration by pushing configurations to SonarQube Cloud. @@ -312,6 +243,7 @@ docker run -v ./files:/app/files ghcr.io/sonar-solutions/sonar-reports:latest \ | Option | Description | Default | |--------|-------------|---------| +| `--config` | Path to JSON configuration file (alternative to CLI arguments) | - | | `--url` | SonarQube Cloud URL | `https://sonarcloud.io/` | | `--edition` | SonarQube Cloud license edition | - | | `--export_directory` | Directory containing mapping files | `/app/files/` | @@ -347,7 +279,7 @@ The tool tracks completed tasks and resumes from the last completed task. --- -### Phase 5: Pipelines (Optional) +### Pipelines (Optional) Automatically update CI/CD pipeline configurations to use SonarQube Cloud. @@ -391,43 +323,6 @@ docker run -v ./files:/app/files ghcr.io/sonar-solutions/sonar-reports:latest \ ## Additional Commands -### Full Migrate - -Run a complete end-to-end migration from a single JSON config file. Automatically runs extract, structure, org mapping, mappings, and migrate phases in sequence. - -```bash -docker run -v ./files:/app/files ghcr.io/sonar-solutions/sonar-reports:latest \ - full_migrate -``` - -#### Arguments - -| Argument | Description | -|----------|-------------| -| `CONFIG_FILE` | Path to a JSON configuration file (see below) | - -#### Config File Format - -```json -{ - "sonarqube": { - "url": "https://your-sonarqube-server.com", - "token": "YOUR_SQS_ADMIN_TOKEN" - }, - "sonarcloud": { - "url": "https://sonarcloud.io/", - "token": "YOUR_SQC_TOKEN", - "enterprise_key": "your-enterprise", - "org_key": "your-org-key" - }, - "settings": { - "export_directory": "/app/files", - "concurrency": 10, - "timeout": 60 - } -} -``` - ### Analysis Report Parse a migration run's `requests.log` and generate a CSV summary of all API calls with success/failure outcomes. @@ -518,10 +413,11 @@ After the migration completes, verify your SonarQube Cloud environment and prepa ### Structure Output -| File | Purpose | Requires Editing | -|------|---------|------------------| -| `organizations.csv` | Organization mappings | Yes - fill in `sonarcloud_org_key` | -| `projects.csv` | Project mappings | No | +| File | Purpose | +|------|---------| +| `organizations.csv` | Organization mappings | +| `projects.csv` | Project mappings | +> **`organizations.csv` requires editing when using manual mode.** ### Mappings Output