Operations Guide

Document maturity: DRAFT

Referenced documentation

Introduction

The SonarQube component is part of Software Factory as a Package (SWaaP).

The component is in charge of collecting and analyzing source code to provide detailed reports on code quality. It enables users to identify issues such as styling errors, code defects, duplication, lack of test coverage, or excessive complexity. It also allows users to continuously monitor and improve code reliability, application security, and maintainability by reducing technical debt.

Learn more about it .

Service Catalog Items

The catalog items are defined according to the RACI in the LLD.

Grant access to SonarQube

Access to the platform is handled through the same “Get Engineering Software Solution” bundle used for other services.

We recommend:

• Using SAML SSO, user accounts are automatically provisioned on first login, and authorization is managed primarily through external group mapping from the IdP (preferred).

• Local SonarQube users remain supported for break-glass or administrative access but are generally discouraged for regular users.

  See Authentication and provisioning overview

  See Overview of SAML support

• Group synchronization can be enabled for any SAML provider including Azure, Keycloak and Okta, and also any SAML endpoint. To enable the SAML group attribute, navigate to Administration > Configuration > General Settings > Authentication > SAML > Configuration .

  See Group synchronization overview

• Permission Templates are configured according to the LLD, including restricting access for the default sonar-users group and granting elevated permissions only to designated administrative groups.

Create a SonarQube Project

SonarQube projects are the core units to track, as they drive license costs and can be created manually or through CI/CD.

It is recommended to entrust project creation to the tenant owner.

To create a SonarQube Project, ask users for the following information:

• Project key:
  • Tooltip: Unique identifier for the project. It should be like GBU_BL_ProjectName, where the projectName is similar to the GitLab project name.
  • Content:
    • Type: single-line text
    • Length: [1;128]
    • Value: Alphanumeric characters plus special characters -_.:
    • Regex: ^[a-zA-Z0-9\-_.:]{1,400}$
  • Default value: None
  • Example: swf-swaap-frontend
• Project name:
  • Tooltip: Display name visible on the web interface.
  • Content:
    • Type: single-line text
    • Length: [1;255]
    • Value: alphanumeric or special characters
    • Regex: ^.{1,255}$
  • Default value: None
  • Example: SoftwareFactory Swaap product Frontend application
• Visibility:
  • Tooltip: Criterion determining whether a project is visible to all users.
  • Content:
    • Type: boolean
    • Value: Private or Public
  • Default value: Private
• Project administrators:
  • Tooltip: People who will administer the project
  • Content:
    • Type: list
    • Length: [1;∞]
    • Value: group names or user emails
    • Regex: /.*/
  • Default value: the requester’s email
  • Example: jane.doe@fr.thalesgroup.com,swf-admin-team,swf-dev-team
• (optional) Description:
  • Tooltip: Description visible to everyone
  • Content:
    • Type: multi-line text
    • Length: [0;∞]
    • Value: any
    • Regex: /.*/
  • Default value: None
  • Example: A good description for this project

Then the expected actions are:

• Create the project
  • In the top navigation bar of SonarQube Server, select the Projects tab.
  • In the top right corner, select the Create Project > Local Project button.
• Ensure project-level Administer permissions are granted

See how to Create your SonarQube Server project manually

See Manage project members and permissions

Manage project members and permissions

Assign team members and/or groups to a given project, in accordance with the principle of least privilege.

It is recommended to entrust the project membership and permission management to the tenant owner. Prefer assigning permissions to groups and reserve individual user assignments for exceptions.

• Prerequisites:
  • Groups (groups mapped from SAML/IdP are preferred over local groups).
  • Permission Template already deployed as per LLD (for a developer group (end users): Browse, See Source Code, Execute Analysis).

To assign team members and/or groups to a given project, ask users for the following information:

• Project key:
  • Tooltip: Unique identifier for the project.
  • Content:
    • Type: single-line text
    • Length: [1;128]
    • Value: Alphanumeric characters plus special characters -_.:
    • Regex: ^[a-zA-Z0-9\-_.:]{1,400}$
  • Default value: None
  • Example: swf-swaap-frontend
• Groups/Members to add/remove:
  • Tooltip: Groups/Members to add/remove with their respective permissions
  • Content:
    • Type: list
    • Length: [1;∞]
    • Value: group names or user emails
    • Regex: /.*/
  • Default value: the requester’s email
  • Example: jane.doe@fr.thalesgroup.com,swf-admin-team,swf-dev-team
• Permission set per group/member (choose from)
  • Tooltip: Set of permissions to assign to the groups/members
  • Content:
    • Type: checkbox list
    • Values:
      • Browse
      • See Source Code
      • Execute Analysis
      • Administer Issues
      • Administer Security Hotspots
      • Administer (full project admin)
    • Default: None

Then the expected actions are:

• Access the project’s permission settings
• Add groups or users and assign their permissions

See Setting project permissions

See also Access Control and Permissions

Run a Sonar analysis

To perform a source analysis on a project, a user or service account must be granted the ‘Execute Analysis’ permission through the project’s permission settings.

For further details, refer See Managing Project Members and Permissions

Analyze sonar results

To access the sonar analysis results, a user must be granted the ‘Browse’ permission via the project’s permission settings.

For further details, refer to the section See Managing Project Members and Permissions

Create a quality profile

Quality Profiles define the rules to be applied to a project for a specific language.

We recommend that only Tenant owner should manage the creation of quality profile. Quality profiles may be used by many projects and can have multiple authorized owners. To avoid unwanted modifications, admins should ensure that any new permission requests originate from the profile’s responsible team.

To create a quality profile, ask users for the following information:

• Language:
  • Tooltip: Programming language associated with the profile.
  • Content:
    • Type: choice list
    • Values:
      • ABAP
      • Ansible
      • Apex
      • Azure Resource Manager
      • C/C++/Objective-C
      • C#
      • CloudFormation
      • COBOL
      • CSS
      • Dart
      • Docker
      • Flex
      • Go
      • HTML
      • Java
      • JavaScript/TypeScript
      • JCL
      • JSON
      • Kotlin
      • Kubernetes/Helm
      • PHP
      • PLI
      • PL/SQL
      • Python
      • RPG
      • Ruby
      • Rust
      • Scala
      • Secrets
      • Swift
      • Terraform
      • T-SQL
      • VB.NET
      • VB6
      • XML
      • YAML
    • Default: None
• Profile name:
  • Tooltip: Name of the new quality profile.
    • Content:
      • Type: single-line text
      • Length: [1;51]
      • Value: alphanumeric characters and special characters
      • Regex: /.*/
    • Default value: None
    • Example: swf-swaap-frontend
• (optional) Base profile to extend:
  • Tooltip: Extend a built-in or another custom profile
    • Content:
      • Type: single-line text
      • Length: [1;255]
      • Value: alphanumeric characters and special characters
      • Regex: /.*/
    • Default value: Sonar way (Built-in)
    • Example: Thales C++ profile
• Groups or members to add as owners:
  • Tooltip: Groups or members to add as owners
  • Content:
    • Type: list
    • Length: [1;∞]
    • Value: group names or user emails
    • Regex: /.*/
  • Default value: the requester’s email
  • Example: jane.doe@fr.thalesgroup.com,swf-admin-team,swf-dev-team

Then the expected actions are:

• Create or extend the profile
• Set groups/members ownership

See Create / Restore Quality profile

See also how to Create a quality profile

See Add quality profile owners (“Administer Quality Profiles” permission)

Add quality profile owners (“Administer Quality Profiles” permission)

Delegate the maintenance of a quality profile to a group or user.

We recommend designating a quality profile administrator, allowing projects to manage their quality profiles independently. The addition of a quality profile administrator can only be done for custom quality profiles.

To add quality profile owners, ask users for the following information:

• Language:
  • Tooltip: Programming language associated with the profile.
  • Content:
    • Type: choice list
    • Values:
      • ABAP
      • Ansible
      • Apex
      • Azure Resource Manager
      • C/C++/Objective-C
      • C#
      • CloudFormation
      • COBOL
      • CSS
      • Dart
      • Docker
      • Flex
      • Go
      • HTML
      • Java
      • JavaScript/TypeScript
      • JCL
      • JSON
      • Kotlin
      • Kubernetes/Helm
      • PHP
      • PLI
      • PL/SQL
      • Python
      • RPG
      • Ruby
      • Rust
      • Scala
      • Secrets
      • Swift
      • Terraform
      • T-SQL
      • VB.NET
      • VB6
      • XML
      • YAML
    • Default: None
• Profile name:
  • Tooltip: Name of the quality profile.
    • Content:
      • Type: single-line text
      • Length: [1;51]
      • Value: alphanumeric characters and special characters
      • Regex: /.*/
    • Default value: None
    • Example: swf-swaap-frontend
• Groups or members to add as owners:
  • Tooltip: Groups or members to add as owners
  • Content:
    • Type: list
    • Length: [1;∞]
    • Value: group names or user emails
    • Regex: /.*/
  • Default value: the requester’s email
  • Example: jane.doe@fr.thalesgroup.com,swf-admin-team,swf-dev-team

Then the expected actions are:

• Access the profile using the provided profile name
• In the Permissions section, select the “Grant permissions to a user or a group” button

See Manage a specific quality profile

See also how to Grant permissions to users

Assign a custom Quality profile to a project

For each project, select a specific profile instead of the default. This action can be performed by a project administrator without requiring intervention from Tenant owners.

See how to Associate a quality profile with projects

Create a quality gate

A Quality gate ensures a minimum level of quality before deployment to production.

We recommend that only the Tenant owner should create or edit global quality gates and set defaults. Users may request the creation of a custom quality gate.

To create a custom quality gate, ask users for the following information:

• Gate name:
  • Tooltip: Name of the new quality gate.
    • Content:
      • Type: single-line text
      • Length: [1;257]
      • Value: alphanumeric characters and special characters
      • Regex: /.*/
    • Default value: None
    • Example: SWF Swaap Gate
• Project key:
  • Tooltip: Unique identifier for the project.
  • Content:
    • Type: single-line text
    • Length: [1;128]
    • Value: Alphanumeric characters plus special characters -_.:
    • Regex: ^[a-zA-Z0-9\-_.:]{1,400}$
  • Default value: None
  • Example: swf-swaap-frontend
• Groups or members to add as owners:
  • Tooltip: Groups or members to add as owners
  • Content:
    • Type: list
    • Length: [1;∞]
    • Value: group names or user emails
    • Regex: /.*/
  • Default value: the requester’s email
  • Example: jane.doe@fr.thalesgroup.com,swf-admin-team,swf-dev-team

Then expected actions are:

• Create the quality gate
• Assign the project(s)
• Add the quality gate owners

See how to Create a custom quality gate

See how to add quality gate owners

Add quality gate owners (“Administer quality gates” permission)

Delegate the maintenance of a quality gate to a user or group.

We recommend adding a quality gate administrator; this allows projects to manage their quality gate independently.
You can only add a quality gate administrator to a custom quality gate.

To add quality gate owners, ask users for the following information:

• Gate name:
  • Tooltip: Name of the new quality gate.
    • Content:
      • Type: single-line text
      • Length: [1;257]
      • Value: alphanumeric characters and special characters
      • Regex: /.*/
    • Default value: None
    • Example: SWF Swaap Gate
• Groups or members to add as owners:
  • Tooltip: Groups or members to add as owners
  • Content:
    • Type: list
    • Length: [1;∞]
    • Value: group names or user emails
    • Regex: /.*/
  • Default value: the requester’s email
  • Example: jane.doe@fr.thalesgroup.com,swf-admin-team,swf-dev-team

Then the expected actions are:

• Access the quality gate
• In the Permissions section, select the “Grant permissions to a user or a group” button

See how to set Quality gate permissions

Assign a custom Quality Gate to a project

This action can be performed by a project administrator without requiring intervention from the tenant owner.

See how to Set quality gate and quality profiles

Create and manage local groups

We do not recommend providing this service to users. We recommend platforms manage permissions through Active Directory groups.

See LLD - User management

See Overview of SAML support

See Managing groups

Delete a Project

Deleting a project can be performed by an end user with the project Administer permission on the project.

See how to Delete your project

Manage Applications (Create, Update, Delete)

A SonarQube Application combines multiple projects into a single view to measure the overall quality of a product.

We recommend delegating the management of Applications to end users as Applications do not generate costs and exist solely to aggregate data across multiple projects, they do not require administration by tenant owner.

See Organize project with Application and Portfolio

See also how to Manage applications

Manage Portfolios (Create, Update, Delete)

A SonarQube Portfolio groups multiple projects or applications to provide an overall view of code quality across an organization.

We recommend delegating the management of portfolios to end users; since portfolios do not generate costs and exist solely to aggregate data across multiple projects, they do not require administration by tenant owners.

See Organize project with Application and Portfolio

See also how to Manage portfolios

Create a Permission Template

Permission Templates are predefined permission that automatically apply to projects matching a criteria (project key patterns).

They simplify access management by eliminating the need to configure permissions individually each time.

Before creating a permission template (with a specific form), collect the following information:

Required Information:

1. Template Name: Descriptive name (e.g., GBU_BL_commun-prefix)
2. Project Key Pattern: Regular expression to match project keys (e.g., GBU_BL_{PREFIX}.*)
3. Groups and Permissions: List of groups with their desired permissions
4. Users and Permissions (if applicable): Individual users with their desired permissions

1. Navigate to Permission Templates:

   • Go to Administration (top menu)
   • Select Security > Permission Templates

2. Create New Template:

   • Select Create button
   • Enter Template Name (use clear, descriptive naming)
   • Enter Project Key Pattern (regex format)
   • Optionally add a Description
   • Select Create

3. Configure Group Permissions:

   • In the template row, locate the Groups column
   • For each required group:
     • Search and select the group
     • Assign appropriate permissions

4. Configure User Permissions (if needed):

   • Do the same with the users

5. Navigate to Project Management Screen: (only for Existing Project)

   • Go to Administration > Project > Management

6. Apply Template:

   • Filter the project to match the regex provided
   • Select All project (eventually check that the result match what requester estimation)
   • Select Bulk Apply Permission Template
   • Select in the dropdown, the newly created permission template

Billing and onboarding

This section aims to describe how billing related to the component is managed and specify offers including access to the component.

Billing & onboarding on TDP

As a component of the SWF product, onboarding and offboarding are managed via Get access to Software Solutions _PostIT tickets, by selecting offername as the offering that includes access to the component.

_Please note that all existing users who have access to the offername offering will automatically have access to this component.

Billing & onboarding on RTDP

_To have access to this component, users should be onboarded to the offer offername.

Billing & onboarding on CASTLE

_To have access to this component, users should be onboarded to the offer offername.

Component deployment and configuration

Requirements & Pre-requisite

All associated ECOL prerequisites are detailed here .

Configuration

Setting Helm values

Mandatory SonarQube values are described in the SWaaP Readme - Helm values .

There’s also a list of required and optional ConfigMaps that are needed. These are described in the SonarQube package readme document

Configuring Kubernetes secrets

The required SonarQube secrets and how they are created are described in the SWaaP Readme - SonarQube secrets .

Deployment & update procedure

The deployment and update procedures are described in the SWaaP Readme - Quick start section .

Test instance for the users

As specified in the LLD, we recommend having a test instance available for the users to test the major SonarQube versions before going in production, as this may break their current workflows.

On this instance the permissions may be more permissive than the recommended governance on SonarQube, to make it easier for the platform team to administrate these users.

We recommend the following settings on the test instance:

• be aligned with the SWaaP version
• have the same version that you will target for your upgrade in production
• have the same plugins that you will target for your production

Regarding the governance, we recommend to:

• Not migrate any project or data (they will import their data automatically at the first scan)
• Not migrate any project permission (they will manage their permission at the first scan)
• Not migrate any quality gates or profiles
• Allow all users to Administer quality profile
• Allow all users to Administer quality gates

That way, users will be fully autonomous to reflect the impacts of the new version on their project. There is a low risk of users overriding default profile or changing others’ profiles. We recommend to explain this in your communication announcing that the test instance is available.

Disabling administer quality gates / profiles permission will increase support requests for your team.

Settings

Setting up SAML with Microsoft Entra ID .

Functional Configuration

SonarQube AI features

The SonarQube AI features may be used to detect AI generated code (based on GitHub Copilot) or to propose AI-generated fixes for your code (experimental feature based on OpenAI’s GPT-4).

We recommend that in both cases these features are disabled as they rely on AI features not yet used in Thales.

To disable the AI features you need to have SonarQube administrator rights. Login to SonarQube and navigate to Configuration tab. From the drop-down menu select General Settings:

• to disable AI generated code detection navigate to AI-Generated Code and from the right screen disable Autodetect AI-Generated Code (slide the button to left)
• to disable tthe AI-generated fixes for your code navigate to AI CodeFix and from the right screen make sure that the Enable AI CodeFix checkbox is unchecked (it should NOT be enabled by default)

SonarQube Web Server - Sessions Duration

The inactivity timeout duration of user sessions, in minutes is set by default to 3 days (4320 minutes). As per security best practices we recommend a maximum duration of 1 day (1440). This can be set through the SONAR_WEB_SESSIONTIMEOUTINMINUTES environment variable. To find out more checkout the documentation .

SonarQube Project Visibility Configuration

We recommend that new projects in SonarQube are created as private by default. This configuration prevents unauthorized access to project data, source code, and issues, especially by unauthenticated users.

To configure this, please follow the official SonarQube documentation:

• Changing the default visibility of new projects .

Logging

This chapter describes details for configuring and accessing:

• File system logs
• Logs from the UI
• Console logs

Server-side logging is controlled by properties set in <SONARQUBE_HOME>/conf/sonar.properties. The standard output of SonarQube logs can be converted to JSON with the environment variable SONAR_LOG_JSONOUTPUT=true. A configuration of the log format is currently not possible.

Log level

The server-side log level can be customized for each log type via the ‘sonar.log.level’ property. Supported values are:

• INFO: the default
• DEBUG: for advanced logs.
• TRACE: show advanced logs and all SQL and Elasticsearch requests. TRACE level logging slows down the server environment, and should be used only for tracking web request performance problems.

Log level by process

The server-side log level can be adjusted more precisely for the four processes of SonarQube server via the following properties:

• sonar.log.level.app : for the Main process of SonarQube (aka WrapperSimpleApp, the bootstrapper process starting the 3 others)
• sonar.log.level.web : for the WebServer
• sonar.log.level.ce : for the ComputeEngineServer
• sonar.log.level.es : for the SearchServer

Output log files by type

All logs are generally plain text (UTF-8), machine-readable, timestamped, and located in the SonarQube <SONARQUBE_HOME>/logs/. The list of available log files include:

• sonar.log -The main SonarQube process log. Contains startup, shutdown, and general server lifecycle messages and critical errors.
• web.log - Application server (HTTP API / web UI) internal logs: servlet handling, web layer exceptions, plugin initialization for web context.
• ce.log - Compute Engine logs: background tasks (analysis post-processing, report generation, task queue handling).
• es.log - Elasticsearch logs: cluster formation, index operations, node state, health and memory issues.
• access.log - HTTP access log (requests to web server / API). Useful for auditing, rate patterns, or tracing specific API calls.

Accessing logs from the UI

License Monitoring

Monitoring SonarQube license consumption is crucial to Avoid Service Disruption, exceeding license limits can block new code analyzes.

Staying within the licensed scope ensures compliance with legal and commercial terms. Finally, early awareness allows enough time to process renewals and initiate procurement procedures.

To check license usage you can:

1. Log in with an account that has System Administrator rights.
2. Navigate to Administration > Configuration > License Manager.
   • Here, you will see key details such as:
     • Edition and Expiry Date of your license
     • Number of Lines
     • Notification threshold
3. Review the Current Consumption Bar to assess how close you are to your limit.

This is updated in real time as projects or lines of code change.

We recommend to configure notifications threshold as proportional of the total licensed line of code instead of a fixed value: 20% of total licensed lines of code.

The notification threshold corresponds to lines of code before limit.

To Change the Notification Threshold:

1. Navigate to Administration > Configuration > License Manager.
2. Select look Edit Notification Threshold.
   • In the threshold field set value that represents 20% of your total license capacity.

API deprecation logs

After an upgrade, you can check if an authenticated client of your SonarQube Server instance uses deprecated Web API endpoints and parameters in order to anticipate their drop. To download the deprecation log from the UI (with the Administer System permission):

1. In the top navigation bar of the SonarQube Server UI, select Administration > System.
2. In the top right corner of the System Info page, click Download Logs > Deprecation Logs

Console logs

SonarQube don’t offer specific guidelines on retrieving console logs, thus it can be collected via industry standard methods.

Monitoring

Monitoring your SonarQube instance is key to keeping it healthy and having happy users.

As a start, you can use this Web API to get an overview of the health of your SonarQube installation: api/system/health

Exposed JMX MBeans

SonarQube Server offers visibility about what happens internally through the exposure of JMX MBeans. In addition to the classical Java MBeans providing information about the ClassLoader, OS, Memory, and Threads you have access to three more MBeans in SonarQube Server:

• ComputeEngine
• Database
• SonarQube

All these MBeans are read-only. It’s not possible to modify or reset their values in real time.

JMX Activation

1. From local: There is nothing to activate to view SonarQube MBeans if your tool is running on the same server as the SonarQube Server.

2. From remote:

• for the WebServer:

# JMX WEB - 10443/10444
sonar.web.javaAdditionalOpts=-Dcom.sun.management.jmxremote=true \
-Dcom.sun.management.jmxremote.ssl=false -Dcom.sun.management.jmxremote.authenticate=true \
-Dcom.sun.management.jmxremote.port=10443 -Dcom.sun.management.jmxremote.rmi.port=10444 \
-Dcom.sun.management.jmxremote.password.file=/opt/sonarsource/sonar/conf/jmxremote.password \
-Dcom.sun.management.jmxremote.access.file=/opt/sonarsource/sonar/conf/jmxremote.access

• For the ComputeEngine, there is no specific javaAdditionalOpts entry, simply amend sonar.ce.javaOpts :

Example of jmxremote.access:

#
# JMX Access Control file
#
reader readonly
admin  readwrite \
    create javax.management.monitor.*,javax.management.timer.*,com.sun.management.*,com.oracle.jrockit.* \
    unregister

Example of jmxremote.password:

#
# JMX Access Password file
#
reader readerpassword
admin  adminpassword

Note: You should apply chmod 600 or 400 on the file jmxremote.password, for security reasons.

Prometheus monitoring

You can monitor your SonarQube instance using SonarQube’s native integration with Prometheus. Through this integration, you can ensure your instance is running properly and know if you need to take action to prevent future issues.

Prometheus monitors your SonarQube instance by collecting metrics from the /api/monitoring/metrics endpoint. Results are returned in OpenMetrics text format. See Prometheus’ documentation on Exposition Formats for more information on the OpenMetrics text format.

Monitoring through this endpoint requires authentication. You can access the endpoint following ways:

• Authorization:Bearer xxxx header: You can use a bearer token during a database upgrade and when SonarQube is fully operational. Define the bearer token in the sonar.properties file using the sonar.web.systemPasscode property.
• X-Sonar-Passcode: xxxxx header: You can use X-Sonar-passcode during database upgrade and when SonarQube is fully operational. Define X-Sonar-passcode in the sonar.properties file using the sonar.web.systemPasscode property.
• username:password and JWT token: When SonarQube is fully operational, system admins logged in with local or delegated authentication can access the endpoint.

For more information about monitoring please access the official page .