> For the complete documentation index, see [llms.txt](https://developer.harness.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.harness.io/internal-developer-portal/3.0/use-idp/software-catalog/create-entity/catalog-discovery/sonarqube.md). # SonarQube Integration The SonarQube integration connects to your SonarQube Server (self-hosted) or SonarQube Cloud instance and brings projects into the IDP Catalog. Once ingested, entities can be registered as new catalog entries or merged into existing ones, enriching them with SonarQube-sourced metadata such as: * Code quality measures * Security hotspots * Quality gate status * Issue analytics For each project, the integration collects the following: | Resource | What it provides | | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Project** | Quality gate status, reliability rating, security rating, SQALE rating, line and branch coverage, duplication metrics, code size, bugs, vulnerabilities, security hotspots, and code smells. | *** ### Before you begin The following are needed to get the integration running: * Ensure the feature flag `IDP_INTEGRATIONS` is enabled. Contact [Harness Support](mailto:support@harness.io) to enable them. * You have the required RBAC permissions to manage integrations. All integration operations require the `IDP_INTEGRATION_EDIT` permission on the `IDP_INTEGRATION` resource type. * A SonarQube user token with global-level `Browse` privileges is available. Generate it via **My Account** → **Security** → **Generate Tokens** in SonarQube. {% hint style="info" %} **PROXY CONFIGURATION** If your environment blocks outbound third-party traffic and routes it through a proxy, you will need to configure proxy settings on your Harness Delegate. Once configured there, the proxy settings are automatically picked up by IDP integrations. No additional setup is needed on the integration side. Here is how to set it up: [Configure delegate proxy settings](/harness-ai/use-harness-platform/delegates/delegate/manage-delegates/configure-delegate-proxy-settings.md) {% endhint %} *** ### Enable the SonarQube integration {% hint style="info" %} The SonarQube integration is available at the **Account**, **Organization**, and **Project** levels of Harness. Navigate to the appropriate scope of the Internal Developer Portal to add or manage SonarQube integrations. {% endhint %} #### 1. Navigate to the integrations page 1. In Harness, open the **Internal Developer Portal**. 2. From the left sidebar, click **Configure**. 3. In the left navigation menu, click **Integrations**. Figure 1: Navigation Path of SonarQube Integration 4. On the Integrations page, click **+ New Integration** at the top. 5. Select **SonarQube** from the integration type picker. You will be taken to the **Auto Discover SonarQube Integration** page. #### 2. Configure setup & connectivity This section connects Harness IDP to your SonarQube instance. Figure 2: Setup & Connectivity 1. Enter a name in the **Integration Name** field. This name appears on the integration card on the **Integrations** page (e.g., `SonarQube Production`). 2. Select the **SonarQube Type** from the dropdown: * **SonarQube Cloud** - for cloud-hosted SonarQube (sonarcloud.io). * **SonarQube Server** - for self-hosted, on-premises SonarQube. 3. Enter the **SonarQube Host URL**: * For SonarQube Server, this is the base URL of your instance (e.g., `https://sonarqube.example.com`). * For SonarQube Cloud, use the regional endpoint for your organization: * Global: `https://sonarcloud.io` * US region: `https://sonarqube.us` 4. *(SonarQube Cloud only)* Enter the **Organization Key**. This is your SonarQube Cloud organization key (e.g., `my-org`). 5. Under **User Token**, click **Create or Select a Secret** and provide your SonarQube User Token. This token must have global-level `Browse` privileges.

RECOMMENDED SECRETS MANAGER

For SonarQube Integration, we recommend you use the Harness Built-in Secret Manager for storing the SonarQube user token.

6. *(Optional)* Enter one or more **Project Keys** to limit the sync scope. Type a project key and press **Enter** to add it. When left empty, all projects in your SonarQube instance or organization are synced.

SCOPING YOUR INTEGRATION

Every project in SonarQube has a unique project key. Use these to scope each integration appropriately. We recommend creating one integration per project or small group of projects rather than a single integration covering all projects. This makes it easier to manage sync frequency, troubleshoot issues, and control catalog growth.

CHECK NETWORK REACHABILITY

For SonarQube Server (self-hosted) instances, ensure that your SonarQube instance is reachable from within the environment where your Harness Delegate is running. The delegate must have network access to the SonarQube Host URL you configure.

#### 3. Configure mapping & correlation This section defines how SonarQube projects are mapped to IDP catalog entities and how they are correlated with existing catalog records. The integration supports the **Project Entity** type, which imports SonarQube projects as catalog components. Figure 3: Available Entities - Projects **Project entity** 1. Ensure the **Project Entity** toggle is turned on. 2. Under **Entity Registration Behavior**, choose how projects are brought into the catalog: * **Register & Merge** *(Default)* - Registers new entities and updates existing ones when a match is found. This is the recommended option for most setups. * **Register** - Creates new catalog entities from SonarQube projects. Does not merge with existing entities. * **Merge** - Links discovered projects to existing catalog entities. Matching entities are recommended automatically, but you can choose a different one. 3. The default **Kind** is `Component` and **Type** is `Service`. These are pre-configured and apply to all SonarQube project imports. 4. Under **Correlation Mapping**, set the **Ingested Data Path** (from SonarQube) and the corresponding **Catalog YAML Path** (from your IDP entity) to define how records are matched. The operator defaults to `Equals`. Example: | Ingested Data Path | Operator | Catalog YAML Path | | ------------------ | -------- | ----------------- | | `name` | Equals | `name` | 5. Optionally, click **Configure** next to **Configure fields (optional)** to customize which SonarQube fields are synced to the catalog. By default, all available fields are selected. #### 4. Configure advanced settings The **Advanced Settings** section controls how frequently IDP syncs with SonarQube and, for SonarQube Cloud, how far back historical data is pulled. Figure 4: Advanced Settings 1. Select an **Update Frequency** from the dropdown to control how often IDP polls SonarQube for new data. Available options: `10 min`, `30 min`, `1 hour`, `3 hours`, `6 hours`, `12 hours`, `1 day`, `2 days`, `7 days`. 2. Set the **Select start date** to define the earliest date from which IDP will pull SonarQube data. Note that setting this date too far in the past might increase the volume of data pulled on the initial sync and slow it down. 3. Once all sections are configured, click **Confirm & Enable**. A confirmation dialog will appear before the changes are applied. The integration is now enabled and IDP begins syncing data from SonarQube. Discovered projects appear in the [**Discovered** tab](#discovered-tab). *** ### Discover and import SonarQube entities This section covers how to view the SonarQube entities discovered by the integration and import them into your IDP Catalog. #### Discovered tab After the integration runs, all SonarQube projects detected appear in the **Discovered** tab under the **Project** sub-tab. If entities do not appear, use the **Sync** button at the top right to manually refresh. Figure 5: 'Discovered' tab showing SonarQube projects For each discovered entity, you can see its name, the recommended catalog action, kind, type, and the date it was detected. You can choose how to bring entities into the catalog using one of the following actions: * **Register** *(typically used when no matching catalog entity exists)* - Creates a new catalog entity populated with the SonarQube metadata. * **Merge** *(shown as Recommended when a matching catalog entity is found)* - Links the discovered entity to an existing catalog entity, enriching it with SonarQube data. If IDP finds a catalog entity with a matching name or correlation key, **Merge** is pre-selected and the suggested entity is shown automatically. {% hint style="info" %} **BULK IMPORT AND AUTO IMPORT OPTIONS** * **Bulk Import** - Select services individually using the checkboxes, or use the snackbar at the bottom of the page to bulk-select by action type. Open the dropdown to choose **All services**, **Register**, or **Merge (Recommended)**, then click **Import selected services**. * **Auto Import** - Toggle **Auto-import future discovered services** in the top right of the Discovered tab to automatically import all future entities without manual review. You can change this preference at any time. {% endhint %} #### Imported tab The **Imported** tab displays all SonarQube entities that have been brought into the catalog under the **Project** sub-tab. Figure 6: 'Imported' tab showing SonarQube entities linked to catalog entities It displays the following data: | Column | Description | | -------------------- | ----------------------------------------------------------------------------------------------------------------- | | **SonarQube Entity** | The name of the project from SonarQube, along with its import status (for example, **Merged** or **Registered**). | | **Entity** | The linked IDP catalog entity and its ID. | | **Kind** | The catalog entity kind (e.g., `component`). | | **Type** | The catalog entity type (e.g., `service`). | | **Scope** | The Harness scope the entity belongs to (e.g., Account). | | **Imported At** | The timestamp when the entity was imported. | {% hint style="warning" %} **UNLINK AN IMPORTED ENTITY** To stop syncing a specific entity without deleting the catalog entity, use the three-dot menu on any row and select **Unlink**. This stops sync updates while keeping the IDP entity and its existing data intact. {% endhint %} #### Events tab The **Events** tab logs all sync and lifecycle activity for this integration. Use it to verify that syncs are running, confirm that imports completed successfully, and investigate any failures. For the full event type reference and detail panel fields, go to [Integration Events](/internal-developer-portal/use-idp/software-catalog/create-entity/catalog-discovery/integration-events.md). *** ### View SonarQube entities in the catalog Once imported, SonarQube entities are available in the **Catalog** section of IDP as standard catalog entities. Each imported SonarQube project is registered with: * **Kind:** `Component` * **Type:** `Service` * **Scope:** The Harness scope the integration belongs to Open any entity to view SonarQube-sourced data directly on the entity details page. This data is displayed through two dedicated UI components: a card on the **Overview** tab and an **Code Quality** tab. Both require a one-time layout configuration, described in the [next section](#layout-for-sonarqube-components). #### Layout for SonarQube components To display SonarQube data on the [entity details](/internal-developer-portal/use-idp/software-catalog/create-entity/entity-details.md) page, you need to add the two SonarQube components to the relevant entity layout. This is a one-time configuration per entity kind and type. 1. From the left sidebar of IDP, go to **Configure** → **Layout** → **Catalog Entities**. 2. Edit the existing layout for your entity or create a new one. 3. Select the **Entity Kind** (e.g., `component`) and the **Entity Type** (e.g., `service`) that matches your imported SonarQube entities. 4. In the YAML editor, add the `IntegrationsContent` component inside the **Overview** tab's `contents` block, and add a new **Code Quality** tab using the `CodeQualityTab` component. Figure 7: Layout configuration for SonarQube cards in Overview tab and Code Quality tab The relevant YAML additions are: ```yaml - component: IntegrationsContent specs: props: variant: gridItem gridProps: md: 12 ``` ```yaml - name: Code Quality path: /code-quality title: Code Quality contents: - component: CodeQualityTab ``` 5. Click **Save** to apply the layout changes. The SonarQube components will now appear on all entity detail pages of the selected kind and type that have SonarQube data. #### Cards in overview tab After the layout is configured, a `Code Quality` card appears in the **Overview** tab of any entity that has SonarQube data linked to it. The card displays the key SonarQube metadata ingested for that entity, sourced from the entity's [ingested properties](#ingested-properties). Figure 8: SonarQube Cards on the Overview tab If the SonarQube integration has not been configured for the entity, the card shows a **Not configured** state with a link to the Integrations page. #### Code quality tab The **Code Quality** tab provides a more complete view of the SonarQube data for the entity. This tab fetches latest possible data using the integration ID and entity UUID. Figure 9: Code Quality tab showing full SonarQube resource details {% hint style="info" %} **FEATURE HIGHLIGHTS** * The tab shows all available fields for the resource type, including fields not present in the **Overview**. * All the fields are dynamic. * All the cards display data last synced from SonarQube, based on your configured [update frequency](#4-configure-advanced-settings). {% endhint %} #### Ingested properties To inspect the raw data ingested from SonarQube, open the entity and click **View YAML** → **Ingested Properties** in the Entity Inspector. Figure 10: Entity Inspector Page showing Ingested Properties Ingested properties are stored in two sections of the entity YAML: * **`metadata.integration`** - Tracks which integrations are linked to this entity, including the entity action (e.g., `MERGE`) and the linked entity UUID for each integration instance. * **`integration_properties.SonarQube`** - Contains the SonarQube-specific data for the project entity, including top-level metadata fields and quality measures nested under the `measures` key. *** ### Manage the SonarQube integration #### Edit the integration To update the integration name, change the host URL, token, or mapping and correlation settings, navigate to the **Integrations** page, find your SonarQube integration card, and click **View**. From there, click **Configuration** to open the edit screen. #### Suspend auto-discovery If auto-discovery is suspended, new entities will not appear in the **Discovered** tab. Existing imported entities remain unchanged in the catalog, and the sync between SonarQube and their corresponding IDP entities will stop. To suspend auto-discovery: 1. Go to **Integrations** and open your SonarQube integration using the **View** button. 2. Click **Configuration** at the top. 3. In the **Danger Zone** section, click **Suspend**. 4. Confirm the action. You may re-enable it at any time by following the same steps.