= A GitHub Action to check your code with https://github.com/saveourtool/diktat[_diKTat_] :toc: :imagesdir: docs/images :tip-caption: pass:[💡]

[.float-group]

[.left] image::https://img.shields.io/badge/License-MIT-yellow.svg[License: MIT,link="https://opensource.org/licenses/MIT"]

[.left] image::https://badgen.net/github/release/saveourtool/benedikt/latest?color=green[GitHub release,link=https://github.com/saveourtool/benedikt/releases/latest]

[.left] image::https://badgen.net/badge/icon/Ubuntu?icon=terminal&label&color=green[Ubuntu Linux]

[.left] image::https://badgen.net/badge/icon/macOS?icon=apple&label&color=green[macOS]

[.left] image::https://badgen.net/badge/icon/Windows?icon=windows&label&color=green[Windows]

[TIP]

An always updated version of this document is available link:https://saveourtool.github.io/benedikt/ebook.pdf[here] as a PDF e-book.

== Features

• Customizable diktat-analysis.yml xref:#config[location]. You can use the rule set configuration with an alternate name or at a non-default location.

• Customizable JVM xref:#java-setup[vendor and version]. You can run diKTat using a default JVM, or you can set up your own one.

• Customizable xref:#reporter[reporter] (SARIF or Checkstyle XML).

• Allows multiple xref:#input-paths[input paths]. If you have a multi-module project and only wish to check certain directories or modules, you can configure the action accordingly.

• The summary page contains statistic about detected errors:

• image::check-summary.png[diKTat Check summary]

== Usage

In the simplest scenario, the action can be used without input parameters; you just need to check out your code first, using https://github.com/marketplace/actions/checkout[`actions/checkout`]:

[source,yaml]

jobs: diktat_check: name: 'diKTat Check' runs-on: ubuntu-latest

steps:
  - uses: actions/checkout@v4

  - uses: saveourtool/benedikt@v2

== Configuration

[#config] === config: custom configuration file

• Default: diktat-analysis.yml
• Required: no

You can override the name or the path of your YAML configuration file using the config input parameter, e. g.:

[source,yaml]

  - uses: saveourtool/benedikt@v2
    with:
      config: path/to/diktat-analysis-custom.yml

[#reporter] === reporter: requesting a type of reporter

If you wish, you can report errors in a different format.

• Default: sarif
• Required: no
• Possible values: any of the following.

** sarif: report errors in the https://github.com/microsoft/sarif-tutorials/blob/main/docs/1-Introduction.md#what-is-sarif[_SARIF_] format. The output file will be named report.sarif and automatically uploaded to GitHub using the https://github.com/github/codeql-action/tree/v2/upload-sarif[`upload-sarif`] action. This will enable the check results to be shown as annotations in the pull request: + image::sarif-reporting-pr.png[diKTat SARIF reporting (Pull Request)] + as well as in the Code scanning alerts section of your repository: + image::sarif-reporting-code-scanning-alerts.png[diKTat SARIF reporting (Code scanning alerts)]

** checkstyle: this is the reporter of choice if you ever encounter issues with the sarif reporter. Errors are reported in the https://github.com/checkstyle/checkstyle[_Checkstyle-XML_] format to the file named checkstyle-report.xml. The report is then consumed by the https://github.com/reviewdog/reviewdog[`reviewdog] tool and uploaded to _GitHub_, resulting in code annotations similar to those produced by thesarif` reporter: + image::checkstyle-xml-reporting.png[Checkstyle-XML reporting assisted by reviewdog]

[#input-paths] === input-paths: custom source sets

• Default: none
• Required: no

One or more patterns which indicate the files or directories to check. Use a multiline string to specify multiple inputs.

• If an input is a path to a file, it is passed to diKTat as-is:

• [source,yaml]

  • uses: saveourtool/benedikt@v2 with: input-paths: | path/to/file.kt

• If an input is a path to a directory, the directory is recursively traversed, and all \*.kt and *.kts files are passed to diKTat.

• [source,yaml]

  • uses: saveourtool/benedikt@v2 with: input-paths: | src/main/kotlin src/test/kotlin

• If an input is an https://ant.apache.org/manual/dirtasks.html#patterns[_Ant_-style path pattern] (such as \\**/*.kt), diKTat expands it into the list of files that match the path pattern. Path patterns may be negated, e. g.: !src/\**/*Test.kt or !src/\**/generated/**.

• [source,yaml]

  • uses: saveourtool/benedikt@v2 with: input-paths: | /*.kt */.kts !/generated/**

If this input parameter is not specified, this is equivalent to setting it to ., meaning diKTat will check all \*.kt and *.kts files in the project directory unless configured otherwise.

[#java-setup] === java-distribution and java-version: running diKTat using a custom JVM

It's possible to run diKTat with a custom JVM using the https://github.com/actions/setup-java[`actions/setup-java`] action. The following input parameters may be specified:

• java-distribution: the Java distribution, see the https://github.com/actions/setup-java/blob/main/README.md#supported-distributions[list of supported distributions].

Default: temurin Required: no

• java-version: the Java version to set up. Takes a whole or semver Java version. See https://github.com/actions/setup-java/blob/main/README.md#supported-version-syntax[examples of supported syntax].

Default: none Required: no

[NOTE] Setting just the java-distribution property in order to use a custom JDK is not sufficient: you'll need to set both java-distribution and java-version:

[source,yaml]

  - uses: saveourtool/benedikt@v2
    with:
      java-distribution: 'temurin'
      java-version: 17

=== fail-on-error: suppressing lint errors

• Default: true
• Required: no

If false, the errors are still reported, but the step completes successfully. If true (the default), then lint errors reported by diKTat are considered fatal (i.e. the current step terminates with a failure):

[source,yaml]

  - uses: saveourtool/benedikt@v2
    with:
      fail-on-error: true

[NOTE]

This flag only affects the case when diKTat exits with code 1. Higher link:https://diktat.saveourtool.com/diktat-cli/#exit-codes[exit codes] are always fatal.

=== debug: enabling debug logging

• Default: false
• Required: no

Debug logging can be enabled by setting the debug input parameter to true:

[source,yaml]

  - uses: saveourtool/benedikt@v2
    with:
      debug: true

== Outputs

The action returns the exit code of the command-line client using the exit-code output parameter, e. g.:

[source,yaml]

jobs: diktat_check: name: 'diKTat Check' runs-on: ubuntu-latest

steps:
  - uses: actions/checkout@v4

  - id: diktat
    uses: saveourtool/benedikt@v2

  - name: 'Read the exit code of diKTat'
    if: ${{ always() }}
    run: echo "diKTat exited with code ${{ steps.diktat.outputs.exit-code }}"
    shell: bash

The exit codes are documented link:https://diktat.saveourtool.com/diktat-cli/#exit-codes[here].