gitlab-code-quality-plugin

This Maven plugin allows you to transform XML reports created by code quality tools like SpotBugs and Checkstyle into a JSON format supported by GitLab to displayed identified issues in the merge request widget.

Usage

Step 1: Set up SpotBugs and/or Checkstyle

As this plugin processes XML reports of other code quality tools, you have to set up the Maven plugins for SpotBugs and/or Checkstyle first.

Such a setup could look like this:

<project>
  <build>
    <plugins>

      <!-- SpotBugs -->
      <plugin>
        <groupId>com.github.spotbugs</groupId>
        <artifactId>spotbugs-maven-plugin</artifactId>
        <version>4.7.3.3</version>
        <executions>
          <execution>
            <phase>verify</phase>
            <goals>
              <goal>spotbugs</goal>
            </goals>
          </execution>
        </executions>
      </plugin>

      <!-- Checkstyle -->
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-checkstyle-plugin</artifactId>
        <version>3.2.1</version>
        <executions>
          <execution>
            <phase>verify</phase>
            <goals>
              <goal>checkstyle</goal>
            </goals>
          </execution>
        </executions>
        <configuration>
          <configLocation>
            https://raw.githubusercontent.com/checkstyle/checkstyle/master/src/main/resources/google_checks.xml
          </configLocation>
          <linkXRef>false</linkXRef>
        </configuration>
        <dependencies>
          <dependency>
            <groupId>com.puppycrawl.tools</groupId>
            <artifactId>checkstyle</artifactId>
            <version>10.9.3</version>
          </dependency>
        </dependencies>
      </plugin>

    </plugins>
  </build>
</project>

Step 2: Add the plugin to your pom.xml

Now add the following plugin definition to your pom.xml:

<project>
  <build>
    <plugins>

      <!-- ====================================================== -->
      <!--  maven-checkstyle-plugin, spotbugs-maven-plugin, etc.  -->
      <!-- ====================================================== -->

      <plugin>
        <groupId>de.chkal.maven</groupId>
        <artifactId>gitlab-code-quality-plugin</artifactId>
        <version>1.1.0</version>
        <executions>
          <execution>
            <phase>verify</phase>
            <goals>
              <goal>generate</goal>
            </goals>
          </execution>
        </executions>
      </plugin>

    </plugins>
  </build>
</project>

Without any explicit configuration, the plugin will look for XML reports in the following locations:

• target/spotbugsXml.xml

• target/checkstyle-result.xml

If corresponding XML files are found and contain at least one issue, the plugin will generate the following JSON file:

• target/gl-code-quality-report.json

Step 3: Add the plugin to your pom.xml

Finally, you will have to tell GitLab about generated JSON file by modifying your .gitlab-ci.yml file like this:

build:
  stage: build
  image: ...
  script:
    - ...
  artifacts:
    reports:
      codequality:
        - target/gl-code-quality-report.json

With these changes, GitLab will show all findings in the merge request widget.

Advanced configuration

In most cases, no explicit configuration of the plugin is required. But depending on your needs, fine-tuning the configuration may be valuable.

The following example shows all available configuration parameters with their default values:

<project>

  <build>
    <plugins>

      <!-- ====================================================== -->
      <!--  maven-checkstyle-plugin, spotbugs-maven-plugin, etc.  -->
      <!-- ====================================================== -->

      <plugin>
        <groupId>de.chkal.maven</groupId>
        <artifactId>gitlab-code-quality-plugin</artifactId>
        <version>1.1.0</version>
        <executions>
          <execution>
            <goals>
              <goal>generate</goal>
            </goals>
          </execution>
        </executions>
        <configuration>

          <!-- Whether to enable support for SpotBugs -->
          <spotbugsEnabled>true</spotbugsEnabled>

          <!-- Location of the SpotBugs XML report -->
          <spotbugsInputFile>${project.build.directory}/spotbugsXml.xml</spotbugsInputFile>

          <!-- Whether to enable support for Checkstyle -->
          <checkstyleEnabled>true</checkstyleEnabled>

          <!-- Location of the Checkstyle XML report -->
          <checkstyleInputFile>${project.build.directory}/checkstyle-result.xml</checkstyleInputFile>

          <!-- Location of the JSON output file -->
          <outputFile>${project.build.directory}/gl-code-quality-report.json</outputFile>

        </configuration>
      </plugin>

    </plugins>
  </build>
</project>

Multi-module configuration

If you want to use this plugin in a Maven multi-module project, you can simply add the plugin to one of the parent POMs which ensures that the plugin is invoked for all reactor modules. This will create one JSON output file for each module.

Unfortunately, GitLab only supports a single code quality JSON file per job (see this issues for details). To work around this limitation, you can use jq in your pipeline to merge all JSON reports into a single one and use this instead.

See the following pipeline definition for an example:

build:
  stage: build
  image: ...
  before_script:
    - apt-get update && apt-get install -y jq
  script:
    - ...
  after_script:
    - find . -name gl-code-quality-report.json -print | xargs cat | jq -s "add" > merged-gl-code-quality-report.json
  artifacts:
    reports:
      codequality:
        - merged-gl-code-quality-report.json

CLI usage

The plugin may also be used and configured using the Maven CLI. Available configuration properties are:

• glcqp.spotbugsEnabled

• glcqp.spotbugsInputFile

• glcqp.checkstyleEnabled

• glcqp.checkstyeInputFile

• glcqp.outputFile

They are used like this:

mvn de.chkal.maven:gitlab-code-quality-plugin:1.1.0:check \
    -Dglcqp.spotbugsEnabled=true \
    -Dglcqp.spotbugsInputFile=target/spotbugsXml.xml \
    -Dglcqp.checkstyleEnabled=true \
    -Dglcqp.checkstyeInputFile=target/checkstyle-result.xml \
    -Dglcqp.outputFile=target/gl-code-quality-report.json

Using the latest snapshots

The latest snapshots of this plugin are deployed to the Sonatype OSSRH repository. To use these latest snapshots, you will have to modify your pom.xml like this:

<project>

  <build>
    <plugins>

      <!-- ====================================================== -->
      <!--  maven-checkstyle-plugin, spotbugs-maven-plugin, etc.  -->
      <!-- ====================================================== -->

      <plugin>
        <groupId>de.chkal.maven</groupId>
        <artifactId>gitlab-code-quality-plugin</artifactId>
        <version>1.2.0-SNAPSHOT</version>
        <executions>
          <execution>
            <goals>
              <goal>generate</goal>
            </goals>
          </execution>
        </executions>
      </plugin>

    </plugins>
  </build>

  <!-- Sonatype snapshots for plugins -->
  <pluginRepositories>
    <pluginRepository>
      <id>sonatype-ossrh-snapshots</id>
      <url>https://oss.sonatype.org/content/repositories/snapshots</url>
    </pluginRepository>
  </pluginRepositories>

</project>