Soundcheck SonarQube Integration
Spotify Plugins for Backstage: Soundcheck - SonarQube Integration
SonarQube integration plugin for Soundcheck.
SonarQube integration plugin supports the extraction of the following facts:
- Spotify Plugins for Backstage: Soundcheck - SonarQube Integration
Prerequisites
Configure SonarQube integration in Backstage
Integrations are configured at the root level of app-config.yaml
, here's an example configuration for SonarQube:
soundcheck:
collectors:
sonarqube:
token: Token
# Alternatively you may use username and password
# username:
# password:
# If you wish to override the api URL
# baseUrl: https://sonarqube.com
Add the SonarQubeFactCollector to Soundcheck
First add the package: yarn workspace backend add @spotify/backstage-plugin-soundcheck-backend-module-sonarqube
Then in packages/backend/src/plugins/soundcheck.ts
, add the SonarQubeFactCollector
:
import { SoundcheckBuilder } from '@spotify/backstage-plugin-soundcheck-backend';
import { Router } from 'express';
import { PluginEnvironment } from '../types';
+ import { SonarQubeFactCollector } from '@spotify/backstage-plugin-soundcheck-backend-module-sonarqube';
export default async function createPlugin(
env: PluginEnvironment,
): Promise<Router> {
return SoundcheckBuilder.create({ ...env })
.addFactCollectors(
+ SonarQubeFactCollector.create(env.logger)
)
.build();
}
New Backend System
If you are using the New Backend System, instead of the above, you can just add
the following to your packages/backend/src/index.ts
file:
const backend = createBackend();
backend.add(import('@spotify/backstage-plugin-soundcheck-backend'));
+ backend.add(import('@spotify/backstage-plugin-soundcheck-backend-module-sonarqube'));
// ...
backend.start();
See the soundcheck-backend documentation for additional details on creating the Soundcheck backend.
Rate Limiting (Optional)
This fact collector can be rate limited in Soundcheck using the following configuration:
soundcheck:
job:
workers:
sonarqube:
limiter:
max: 1000
duration: 60000
In this example the fact collector is limited to 1000 executions per minute.
This fact collector handles 429 rate limit errors from SonarQube. Soundcheck will automatically wait and retry requests that are rate limited.
Plugin Configuration
Collection of facts is driven by config. To learn more about the config, see the Defining SonarQube Fact Collectors.
-
Create
sonarqube-facts-collectors.yaml
in the root of your Backstage repository and fill in all your SonarQube fact collectors. A simple example SonarQube fact collector is listed below.Note: this file will be loaded at runtime along with the rest of your Backstage configuration files, so make sure it's available in deployed environments in the same way as your
app-config.yaml
files.---
token: dummy
collects:
- type: projects
filter:
- spec.lifecycle: 'production'
spec.type: 'website'
cache: false -
Add a soundcheck collectors field to
app-config.yaml
and reference the newly createdsonarqube-facts-collectors.yaml
# app-config.yaml
soundcheck:
collectors:
sonarqube:
$include: ./sonarqube-facts-collectors.yaml
Defining SonarQube Fact Collectors
This section describes the data shape and semantics of SonarQube Fact Collectors.
Overall Shape Of A SonarQube Fact Collector
The following is an example of a descriptor file for a SonarQube Fact Collector:
---
baseUrl: https://sonarqube.com
token: dummy
collects:
- type: project
filter:
- spec.lifecycle: 'production'
spec.type: 'website'
cache: false
See below for details about these fields.
baseUrl
[optional]
The base URL of the SonarQube instance to use. If not provided, the plugin will attempt to use the default URL https://sonarqube.com
.
token
[optional]
The SonarQube token to use for authentication. If not provided, the plugin will attempt to use username and password instead.
username
[optional]
The SonarQube username to use for authentication. If not provided, the plugin will attempt to use token instead.
password
[optional]
The SonarQube password to use for authentication. If not provided, the plugin will attempt to use token instead.
collects
[required]
An array describing which facts to collect and how to extract them. See below for details about the overall shape of a fact extractor.
Overall Shape Of A Fact Extractor
Each extractor supports the fields described below.
type
[required]
The type of the extractor (e.g. projects, project-tags, issues).
frequency
[optional]
The frequency at which the fact extraction should be executed. Possible values are either a cron expression { cron: ... }
or HumanDuration.
If provided it overrides the default frequency provided at the top level. If not provided it defaults to the frequency provided at the top level. If neither extractor's frequency nor default frequency is provided the fact will only be collected on demand.
Example:
frequency:
minutes: 10
filter
[optional]
A filter specifying which entities to collect the specified facts for. Matches the filter format used by the Catalog API. If provided it overrides the default filter provided at the top level. If not provided it defaults to the filter provided at the top level. If neither extractor's filter nor default filter is provided the fact will be collected for all entities.
cache
[optional]
If the collected facts should be cached, and if so for how long. Possible values are either true
or false
or a nested { duration:
HumanDuration }
field.
If provided it overrides the default cache config provided at the top level. If not provided it defaults to the cache config provided at the top level. If neither extractor's cache nor default cache config is provided the fact will not be cached.
Example:
cache:
duration:
hours: 24
Entity configuration
In your catalog-info.yaml
add the following metadata annotation to allow the plugin to map an entity to a project in SonarQube.
metadata:
annotations:
sonarqube.org/project-key: test-project-key
Collecting Projects Fact
Projects fact contains information about projects from SonarQube Projects API.
Shape of A Projects Fact Collector
The shape of a Projects Fact Collector matches the Overall Shape Of A SonarQube Fact Collector (restriction: type: projects
).
The following is an example of the Projects Fact Collector config:
- type: projects
cache: true
frequency:
cron: '0 * * * *'
Collecting Project Tags Fact
A project tags fact contains information about project tags from SonarQube Project Tags API.
Shape of A Project Tags Fact Collector
The shape of a Project Tags Fact Collector matches the Overall Shape Of A SonarQube Fact Collector (restriction: type: project-tags
).
The following is an example of the Project Tags Fact Collector config:
- type: project-tags
cache: true
frequency:
cron: '0 * * * *'
Collecting Issues Fact
An issues fact contains information about issues from SonarQube Issues API.
Shape of A Issues Fact Collector
The shape of an Issues Fact Collector matches the Overall Shape Of A SonarQube Fact Collector (restriction: type: issues
).
The following is an example of the Issues Fact Collector config:
- type: issues
cache: true
frequency:
cron: '0 * * * *'
Collecting Measures Fact
A measures fact contains information about measures from SonarQube Measures API.
Shape of A Measures Fact Collector
The shape of a Measures Fact Collector matches the Overall Shape Of A SonarQube Fact Collector (restriction: type: measures
).
The following is an example of the Measures Fact Collector config:
- type: measures
cache: true
frequency:
cron: '0 * * * *'
Configure metric keys
Measures fact can be configured to which metrics should be fetched. By default, it will fetch the following metric keys:
- ncloc
- complexity
- violations
- open_issues
To configure it add following section in your config, note that metrics will completely override the default ones, so you need to include them too if you wish to fetch them too.
soundcheck:
collectors:
sonarqube:
collects:
- factName: extendedMeasures
type: measures
metrics:
- ncloc
- complexity
- violations
- open_issues
- bugs
- code_smells
You can see a full list of available metrics in your instance with following HTTP request:
GET https://sonarqube.com/api/metrics/search?ps=500
Authorization: Token
Accept: application/json