This tutorial shows how to setup a SonarQube integration with HCL Accelerate. SonarQube can be used with value streams to measure and track code quality and static code analysis. The SonarQube integration is a little different than other integrations in that it depends on a webhook pattern as discussed below. This pattern is efficient, but requires additional configuration of the SonarQube instance, with a common problem being certificate issues as discussed in this tutorial.

What you will need:

Administrative privileges in HCL Accelerate to…

• Create a user access key
• Create an integration

Administrative privileges in SonarQube to…

• Create a SonarQube auth token
• Create a project or global level webhook
• Troubleshoot and resolve possible issues with HCL Accelerate certificate

1. Webhook Pattern

HCL Accelerate uses a webhook pattern to integrate with SonarQube. A webhook is used to notify HCL Accelerate whenever a project analysis has finished, and HCL Accelerate then retrieves additional information from SonarQube about the analysis. Each integration creates its own HCL Accelerate endpoint to be used by SonarQube as a webhook URL. It is possible to configure multiple SonarQube integrations in this way, or to configure multiple SonarQube instances to webhook a single integration. This depends on your needs.

2. Create the Integration

Create a SonarQube integration in HCL Accelerate. Go to “Settings” > “Integrations”, under the “Plugins” tab, click “Add Integration” for the SonarQube plugin. Provide all required fields.

NOTE: After creating the iteration, check to see if an update is available. It’s a good idea to update integrations to the latest version.

• Integration Name
• SonarQube URL
• SonarQube Auth Token You should be able to create a SonarQube auth token in SonarQube from User > My Account > Security (SonarQube documentation).
• HCL Accelerate User Access Key To create an access key, go to “Settings” > “My profile” and click “Create”. It’s a good idea to name your access key according to the integration that will use it. Make sure to copy the key at this point, since you will not be able to copy it later.

3. Configure the Webhook

Confirm that the integration was created by navigating to the “Integrations” tab in HCL Accelerate. Expand the integration details to see its endpoint URL. Configure a webhook in SonarQube to point to this endpoint URL. SonarQube webhooks can be configured at the project or global level. See SonarQube documentation for details (https://docs.sonarqube.org/latest/project-administration/webhooks/).

Copy Integration Callback URL from HCL Accelerate

Configure SonarQube Webhook with Integration Callback URL

4. Troubleshooting Webhooks

4.1 Determining cause of webhook errors

Current versions of SonarQube do not readily expose webhook failure errors. To troubleshoot a webhook error, first change the log level for the SonarQube compute engine to DEBUG, then run a project analysis to trigger the webhook, then download the logs from the UI (or inspect the logs on the server) and look for a line reporting the webhook error. Refer to SonarQube documentation for details.

4.2 Common Certificate Errors

Because the webhook is https, SonarQube will enforce certificate requirements, which may cause communication to fail. Certificates typically fail due to…

• Trust Store Requirements: See Resolving Self-Signed Certificate Errors below for details.
• Host Name Matching: The host name specified by the certificate must match the host name used by the webhook URL.

5. Resolving Self-Signed Certificate Errors

Although a production instance of HCL Accelerate should use a certificate issued by a Certificate Authority (CA), a full fledged certificate is not always available, especially for test and experimental systems. In such cases, the self-signed certificate that ships with HCL Accelerate can be used instead. However, since it is self-signed, third-party applications like SonarQube must be configured to trust it. Furthermore, the certificate hostname must be the same as the webhook hostname.

5.1 Ensure Valid Certificate Hostname

First ensure that the hostname is configured correctly. If the certificate hostname does not match the actual hostname, either change the actual hostname, or else create a new certificate with the correct hostname. For instance, using OpenSSL as shown below:

openssl req -newkey rsa:2048 -nodes -keyout key.pem -x509 -days 365 -out certificate.pem

If a new certificate was created, HCL Accelerate will need to be configured with it. For docker-compose installations, the certificate should be placed under <install directory>/2.0.4/conf/ssl .

5.2 Copy the Certificate to the SonarQube Server

You can copy the certificate directly from the HCL Accelerate server. For Docker-Compose installations, the certificate can be found under <HCl Accelerate Installation Directory>/conf/ssl. You can also directly download the certificate from a browser. Firefox makes this easy by allowing the certificate to be viewed and downloaded. Once you have the certificate, transfer it to the SonarQube server. For instance, by using SCP, or another other method of choice.

How to use FireFox to copy the certificate – from the URL certificate dropdown, click “More Information”, click “View Certificate” and download the PEM file (FireFox for Mac has a different UI than shown below):

5.3 Add the Certificate to the SonarQube Server’s Trust Store

Option A – Default Trust Store “cacerts”

The default Java trust store is “cacerts”. If this is the trust store being used by SonarQube, then we should be able to add the self-signed certificate to “cacerts”, restart SonarQube, and be on our way.

• • Replace <cert_alias>with a descriptive alias for your cert.
  • Repalce <cert_path.pem> with your actual certificate path.
  • Use actual password if not “changeit”.Add the certificate to the cacerts trust store using the command below.

$JAVA_HOME/bin/keytool -import -trustcacerts -keystore -cacerts -storepass changeit -noprompt -alias <cert_alias> -file <cert_path.pem>

1. Confirm that the certificate was added to cacerts (optional):

$JAVA_HOME/bin/keytool -list -v -cacerts -storepass changeit | grep <cert_alias>

Option B – New Trust Store

In some cases a new trust store might need to be configured, rather than just adding the certificate to cacerts as the default trust store.

1. Create a new key store to be used as a trust store

Run the command below substituting values as needed.

• Replace <cert_alias> with a descriptive alias for your cert.
• Replace <cert_path.pem> with your actual certificate path.
• Replace <new_trust_store.jks> with actual name
• Consider creating a password other than “changeit”.

$JAVA_HOME/bin/keytool -import -trustcacerts -alias <cert_alias> -file <cert_path.pem> -keystore JAVA_HOME/lib/security/<new_trust_store.jks> -storepass changeit -v

2. Configure SonarQube to use as a trust store the .jks file that was just created.

Edit the file <SonarQube Install Path>/conf/sonar.properties to contain the following:

• Replace <path to newly created .jks file> with the actual path
• Use actual password if not “changeit”

#--------------------------------------------------------------------------------------------------
# TRUST STORE
# Overrides default trust store for certificates (Default is $JAVA_HOME\lib\security\cacerts)
sonar.ce.javaAdditionalOpts=-Djavax.net.ssl.trustStore=<path to newly created .jks file> -Djavax.net.ssl.trustStorePassword=changeit -Djavax.net.ssl.trustStoreType=jks

 6. Alternative Workaround for Certificate Errors – Using an http Route

The default webhook route is https. This is certainly recommended for security reasons. It is possible to circumvent certificate requirements by exposing an http route for the webhook, but this should be avoided if at all possible. Unlike self-signed certificates, an http route not only removes the authentication benefit of certificates, but also removes transport layer encryption. It’s important to be aware of this tradeoff if using an http route.

6.1 Expose the http Port

For docker-compose installations use the docker-compose.override.yml configuration file to open port 6004 as shown below. Create this file in your HCL Accelerate installation directory alongside Accelerate’s docker-compose.yml file. If an override file already exists, then add the appropriate configuration under services, reporting-consumer, and ports as needed.

version: '2.1'
services:
 reporting-consumer:
  ports:
   - "6004:6004"

6.2 Modify the webhook

Modify the SonarQube webhook URL from an https reporting-consumer route to an http port 6004 route.

Default https format:

https://<accelerate-hostname>/reporting-consumer/pluginEndpoint/<integration id>/sonarqube/callback

Modified http format:

https://<accelerate-hostname>:6004/pluginEndpoint/<integration id>/sonarqube/callback