Skip to content

Commit a813be4

Browse files
chkalchkal
committed
Added documentation to the README
1 parent 8ac32de commit a813be4

File tree

3 files changed

+201
-3
lines changed

3 files changed

+201
-3
lines changed

‎.readme/gitlab-merge-request-widget.png‎

53.7 KB
Loading

‎README.adoc‎

Lines changed: 201 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,201 @@
1+
= gitlab-code-quality-plugin
2+
:version_stable: 1.0.0-SNAPSHOT
3+
:version_snapshot: 1.0.0-SNAPSHOT
4+
5+
This Maven plugin allows you to transform XML reports created by code quality tools like
6+
https://spotbugs.github.io/[SpotBugs] and https://checkstyle.org/[Checkstyle]
7+
into a JSON format supported by https://about.gitlab.com/[GitLab] to displayed
8+
identified issues in the merge request widget.
9+
10+
image::.readme/gitlab-merge-request-widget.png[]
11+
12+
== Usage
13+
14+
As this plugin processes XML reports of other code quality tools, you have to set up
15+
the Maven plugins for SpotBugs and Checkstyle yourself before adding the plugin.
16+
17+
Then, just add the following plugin definition to your `pom.xml`:
18+
19+
[source,xml,subs="+attributes"]
20+
----
21+
<project>
22+
23+
<build>
24+
<plugins>
25+
26+
<!-- ====================================================== -->
27+
<!-- maven-checkstyle-plugin, spotbugs-maven-plugin, etc. -->
28+
<!-- ====================================================== -->
29+
30+
<plugin>
31+
<groupId>de.chkal.maven</groupId>
32+
<artifactId>gitlab-code-quality-plugin</artifactId>
33+
<version>{version_stable}</version>
34+
<executions>
35+
<execution>
36+
<goals>
37+
<goal>generate</goal>
38+
</goals>
39+
</execution>
40+
</executions>
41+
</plugin>
42+
43+
</plugins>
44+
</build>
45+
</project>
46+
----
47+
48+
Without any explicit configuration, the plugin will look for XML reports in the following locations:
49+
50+
* `target/spotbugsXml.xml`
51+
* `target/checkstyle-result.xml`
52+
53+
If corresponding XML files are found and contain at least one issue, the plugin will
54+
generate the following JSON file:
55+
56+
* `target/gl-code-quality-report.json`
57+
58+
Now you will have to tell GitLab about this file by modifying your `.gitlab-ci.yml` file like this:
59+
60+
[source,yaml]
61+
----
62+
build:
63+
stage: build
64+
image: ...
65+
script:
66+
- ...
67+
artifacts:
68+
reports:
69+
codequality:
70+
- target/gl-code-quality-report.json
71+
----
72+
73+
With these changes, GitLab will show all findings in the merge request widget.
74+
75+
== Advanced configuration
76+
77+
In most cases, no explicit configuration of the plugin is required.
78+
But depending on your needs, fine-tuning the configuration may be valuable.
79+
80+
The following example shows all available configuration parameters with their
81+
default values:
82+
83+
[source,xml,subs="+attributes"]
84+
----
85+
<project>
86+
87+
<build>
88+
<plugins>
89+
90+
<!-- ====================================================== -->
91+
<!-- maven-checkstyle-plugin, spotbugs-maven-plugin, etc. -->
92+
<!-- ====================================================== -->
93+
94+
<plugin>
95+
<groupId>de.chkal.maven</groupId>
96+
<artifactId>gitlab-code-quality-plugin</artifactId>
97+
<version>{version_stable}</version>
98+
<executions>
99+
<execution>
100+
<goals>
101+
<goal>generate</goal>
102+
</goals>
103+
</execution>
104+
</executions>
105+
<configuration>
106+
107+
<!-- Whether to enable support for SpotBugs -->
108+
<spotbugsEnabled>true</spotbugsEnabled>
109+
110+
<!-- Location of the SpotBugs XML report -->
111+
<spotbugsInputFile>${project.build.directory}/spotbugsXml.xml</spotbugsInputFile>
112+
113+
<!-- Whether to enable support for Checkstyle -->
114+
<checkstyleEnabled>true</checkstyleEnabled>
115+
116+
<!-- Location of the Checkstyle XML report -->
117+
<checkstyleInputFile>${project.build.directory}/checkstyle-result.xml</checkstyleInputFile>
118+
119+
<!-- Location of the JSON output file -->
120+
<outputFile>${project.build.directory}/gl-code-quality-report.json</outputFile>
121+
122+
</configuration>
123+
</plugin>
124+
125+
</plugins>
126+
</build>
127+
</project>
128+
----
129+
130+
== Multi-module configuration
131+
132+
If you want to use this plugin in a Maven multi-module project, you can simply add the plugin
133+
to one of the parent POMs which ensures that the plugin is invoked for all reactor modules.
134+
This will create one JSON output file for each module.
135+
136+
Unfortunately, GitLab only supports a single code quality JSON file per job
137+
(see https://gitlab.com/gitlab-org/gitlab/-/issues/9014[this issues] for details).
138+
To work around this limitation, you can use https://stedolan.github.io/jq/[jq] in your
139+
pipeline to merge all JSON reports into a single one and use this instead.
140+
141+
See the following pipeline definition for an example:
142+
143+
[source,yaml]
144+
----
145+
build:
146+
stage: build
147+
image: ...
148+
before_script:
149+
- apt-get update && apt-get install -y jq
150+
script:
151+
- ...
152+
after_script:
153+
- find . -name gl-code-quality-report.json -print | xargs cat | jq -s "add" > merged-gl-code-quality-report.json
154+
artifacts:
155+
reports:
156+
codequality:
157+
- merged-gl-code-quality-report.json
158+
----
159+
160+
== Using the latest snapshots
161+
162+
The latest snapshots of this plugin are deployed to the Sonatype OSSRH repository.
163+
To use these latest snapshots, you will have to modify your `pom.xml` like this:
164+
165+
[source,xml,subs="+attributes"]
166+
----
167+
<project>
168+
169+
<build>
170+
<plugins>
171+
172+
<!-- ====================================================== -->
173+
<!-- maven-checkstyle-plugin, spotbugs-maven-plugin, etc. -->
174+
<!-- ====================================================== -->
175+
176+
<plugin>
177+
<groupId>de.chkal.maven</groupId>
178+
<artifactId>gitlab-code-quality-plugin</artifactId>
179+
<version>{version_snapshot}</version>
180+
<executions>
181+
<execution>
182+
<goals>
183+
<goal>generate</goal>
184+
</goals>
185+
</execution>
186+
</executions>
187+
</plugin>
188+
189+
</plugins>
190+
</build>
191+
192+
<!-- Sonatype snapshots for plugins -->
193+
<pluginRepositories>
194+
<pluginRepository>
195+
<id>sonatype-ossrh-snapshots</id>
196+
<url>https://oss.sonatype.org/content/repositories/snapshots</url>
197+
</pluginRepository>
198+
</pluginRepositories>
199+
200+
</project>
201+
----

‎README.md‎

Lines changed: 0 additions & 3 deletions
This file was deleted.

0 commit comments

Comments
 (0)