GitLab compatible JSON reporter for ktlint

This is a custom reporter for ktlint. It provides output in JSON format that can be parsed by GitLab automatically.

Why?

With the correct artifact format, the GitLab CI can show you what code style violations are present. This helps you with inspecting Merge Requests before merging or keeping your code clean in general.

The reporter outputs the following format:

[
    {
        "type": "issue",
        "check_name": "standard:function-signature",
        "description": "Scenario:28 - Newline expected after opening parenthesis (Rule: standard:function-signature)",
        "categories": ["Style"],
        "location": {
            "path": "path/to/Scenario.kt",
            "lines": {
                "begin": 28
            }
        },
        "severity": "major",
        "fingerprint": "c557e42ba57f1e38f0b1b4f21ba5c610"
    }, ...
]

How do I use the reporter?

1. Download the ktlint-gitlab-reporter.jar from this repository.
2. Copy the JAR file to your Kotlin project.
3. To use the custom reporter, run ktlint --reporter=gitlab,artifact=/path/to/ktlint-gitlab-reporter.jar
   1. If you wish to specify the output directory run ktlint --reporter=gitlab,artifact=/path/to/ktlint-gitlab-reporter.jar,output=path/to/output/output.json

For more information about custom reporters, see the documentation here and the general ktlint documentation here

Other Download Options

Besides downloading the ktlint-gitlab-reporter.jar file directly you can head over to Releases or simply use the published package from Maven Central:

NOTE: The ktlint-gitlab-reporter-legacy.jar uses ktlint version 0.46.1. ktlint implemented some major changes in 0.49.0 and ktlint-gitlab-reporter.jar now supports ktlint 1.0.1!

repositories {
    mavenCentral()
}

dependencies {
    implementation 'io.github.tobi2k:ktlint-gitlab-reporter:x.y.z'
}

Note: AFAIK it is not possible to use the package as a reporter directly in ktlint, but you can automatically download the reporter using your preferred build tool (e.g., Gradle or Maven).

Export artifacts in GitLab CI

This is a very small example on how to incorporate this custom reporter into GitLab CI. It is assumed, that you generally know how to use GitLab CI. Read up here.

Hint: You should specify the output directory in the previous step for this.

Warning: All violations will be marked as major for the overview.

Here output=/build/reports/ktlint/ktlint.json was used.

# gitlab-ci.yml
stages:
  - lint

ktlint:
  stage: lint
  image:
    name: openjdk:11-buster
    entrypoint: [""]
  allow_failure: true
  script:
    - ./gradlew --continue ktlint
  artifacts:
    reports:
      codequality: build/reports/ktlint/ktlint.json

This will generate a pipeline report. View it by going to your project and navigate to CI/CD > Pipelines, select your pipeline and go to the Code Quality tab.

IMPORTANT NOTE: The Code Quality tab is only available with GitLab Premium or Ultimate. However, you can still download the created artifacts on the pipeline overview and view the JSON file.

Example:

Credits

This reporter was inspired by https://github.com/kryanod/ktlint-junit-reporter

License

MIT License

Copyright (c) 2022 Tobias Kalmbach

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

---

GitHub @Tobi2K  ·  Email tobias@kalmbach.dev