Java Checkstyle Reviewer (GitHub Action)

Enforce Java code quality standards in your pull requests with automated Checkstyle analysis.
Powered by reviewdog, this action reports violations as check annotations or inline PR review comments, helping your team keep a consistent code style.

Features

Zero configuration — works out of the box with Google or Sun coding conventions
Flexible reporting — report as check annotations (github-pr-check, github-check) or PR review comments (github-pr-review)
Version control — pin to any Checkstyle version for reproducible builds
Custom rules — bring your own Checkstyle configuration files
Smart filtering — review only changed lines or entire files
Native GitHub integration — status checks and annotations

Quick Start

Add this workflow to your repository at .github/workflows/checkstyle.yml:

name: checkstyle
on: [pull_request]
jobs:
  checkstyle:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: dbelyaev/action-checkstyle@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}

That's it! The action will now analyze Java files in every pull request using Google's coding conventions.

Example

Checkstyle violations appear as inline comments on your pull request, making it easy to identify and fix issues:

View complete example PR with Checkstyle violations and comments

Usage

name: reviewdog
on: [pull_request]
jobs:
  checkstyle:
    name: runner / checkstyle
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: dbelyaev/action-checkstyle@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          reporter: github-pr-review
          level: warning

Security Note: Pin by Tag or by Hash?

When using GitHub Actions, you can pin to a specific version in two ways:

Pinning by Tag

- uses: dbelyaev/action-checkstyle@v3 # pin to the latest major tag

- uses: dbelyaev/action-checkstyle@v3.4.1 # pin to specific version tag

Pros: Convenient, automatically receives updates
Cons: Less secure, as tags can be modified to point to different commits

Pinning by Commit SHA

- uses: dbelyaev/action-checkstyle@0babcc5b0e55e5a8ab6f8a17134f2d613e2bcdda # v3.0.0

Pros: Maximum security, guarantees the exact same code runs every time
Cons: Requires manual updates when new versions are released

Best Practice

GitHub officially recommends pinning actions to a full length commit SHA for production workflows and 3rd party actions to ensure security. For non-critical workflows, major version tags provide a reasonable balance between convenience and safety.

For automated SHA updates, consider using tools like Dependabot (owned by GitHub) or Renovate (owned by mend.io) to keep your actions current while maintaining security.

Required Permissions

This action requires specific GitHub token permissions depending on the reporter you choose. Set these in your workflow's permissions block:

Reporter	Required Permissions
`github-pr-check`	`checks: write`, `contents: read`
`github-check`	`checks: write`, `contents: read`
`github-pr-review`	`pull-requests: write`, `contents: read`

Example — github-pr-check (default reporter):

name: checkstyle
on: [pull_request]
permissions: {}
jobs:
  checkstyle:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      checks: write
    steps:
      - uses: actions/checkout@v6
      - uses: dbelyaev/action-checkstyle@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}

Example — github-pr-review reporter:

name: checkstyle
on: [pull_request]
permissions: {}
jobs:
  checkstyle:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
    steps:
      - uses: actions/checkout@v6
      - uses: dbelyaev/action-checkstyle@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          reporter: github-pr-review

Best Practice: Define empty default permissions at the workflow level (permissions: {}) and grant only the minimum required permissions per job. See GitHub's security hardening guide for details.

Input Parameters

Quick reference for all inputs. Click a name to jump to its detailed description.

Checkstyle inputs:

Name	Required	Default	Description
`checkstyle_config`	No	`google_checks.xml`	Checkstyle ruleset to apply (built-in or custom path).
`checkstyle_version`	No	Latest	Checkstyle version to use for analysis.
`workdir`	No	`.`	Working directory for analysis, relative to repository root.
`properties_file`	No	`''`	Path to a properties file defining variables for the config.
`exclude`	No	`''`	Newline-separated directories/files to exclude.

Reviewdog inputs:

Name	Required	Default	Description
`github_token`	No	`${{ github.token }}`	GitHub token for API authentication.
`reporter`	No	`github-pr-check`	How reviewdog reports violations.
`level`	No	`info`	Severity level for reported violations.
`filter_mode`	No	`added`	Which files/lines reviewdog reports on.
`fail_level`	No	`none`	When reviewdog fails the workflow.
`reviewdog_flags`	No	`''`	Additional flags passed to reviewdog.

The examples below show only the with: block. Place it under the dbelyaev/action-checkstyle step shown in Usage.

Checkstyle Parameters

`checkstyle_config`

Specifies which Checkstyle ruleset to apply during analysis.

Two built-in configurations are available:

google_checks.xml - Google Java Style Guide rules
sun_checks.xml - Sun Code Conventions rules

You can also supply a custom Checkstyle configuration file from your repository. Provide the path relative to the repository root. See the Checkstyle configuration documentation to learn how to create custom rules.

Note: If the specified configuration file is not found or contains invalid XML, the workflow will fail with an error message.

Default: google_checks.xml

Example:

with:
  github_token: ${{ secrets.GITHUB_TOKEN }}
  reporter: github-pr-review
  checkstyle_config: sun_checks.xml

Example PR demonstrating Sun code conventions configuration

`checkstyle_version`

Specifies which Checkstyle version to use for analysis.

Browse available versions on the Checkstyle releases page.

Important: By default, this action automatically uses the latest Checkstyle version. New Checkstyle releases may introduce:

New rules that flag previously accepted code

Modified rule behavior causing different violation counts

Deprecated configuration options

Recommended: Pin to a specific version in production workflows to ensure consistent and reproducible builds. Update the version intentionally when you're ready to address any new violations.

Default: Latest available version

Example:

with:
  github_token: ${{ secrets.GITHUB_TOKEN }}
  reporter: github-pr-review
  checkstyle_version: "12.3.0" # use double quotes for version numbers

`workdir`

Working directory for Checkstyle analysis, relative to the repository root.

Default: '.' (root)

`properties_file`

Path to a properties file (relative to repository root) for defining variables used in your Checkstyle configuration.

Use this to avoid repetition and centralize configuration values. The properties file should use standard Java properties format (key=value).

Note: If the specified file is not found, the workflow will fail. Referenced properties in the config file must exist in the properties file, or Checkstyle will report an error.

Default: '' (empty)

Example:

with:
  github_token: ${{ secrets.GITHUB_TOKEN }}
  reporter: github-pr-review
  checkstyle_config: ./properties_file/test_checks.xml
  properties_file: ./properties_file/additional.properties

Example PR demonstrating properties file usage with custom configuration

`exclude`

Newline-separated list of directories or files to exclude from Checkstyle analysis.

Paths are relative to the repository root. Uses Checkstyle's native -e flag, so subdirectories of excluded paths are also excluded automatically.

Note: Paths are resolved relative to the repository root, not the workdir parameter.

Default: '' (empty — all files are scanned)

Example (single path):

with:
  github_token: ${{ secrets.GITHUB_TOKEN }}
  reporter: github-pr-review
  exclude: "build/generated"

Example (multiple paths):

with:
  github_token: ${{ secrets.GITHUB_TOKEN }}
  reporter: github-pr-review
  exclude: |
    build/generated
    src/main/java/legacy
    third-party

Reviewdog Parameters

`github_token`

GitHub token for API authentication, used by reviewdog to post comments and annotations.

Use ${{ secrets.GITHUB_TOKEN }} (automatically provided by GitHub Actions) or ${{ github.token }} in your workflow.

Note: The required permissions depend on the reporter used:

github-pr-check and github-check require checks: write

github-pr-review requires pull-requests: write

You may need to grant these permissions explicitly in your workflow (recommended), depending on your repository's default GITHUB_TOKEN permissions.

Default: ${{ github.token }}

Example:

with:
  github_token: ${{ secrets.GITHUB_TOKEN }}

For more information about GitHub tokens, see the automatic token authentication documentation.

`reporter`

Determines how reviewdog reports Checkstyle violations in GitHub.

Values: github-pr-check, github-check, github-pr-review

See the reviewdog reporters documentation for detailed examples, screenshots, and permission requirements for each reporter type.

Default: github-pr-check

`level`

Sets the severity level for reported violations, affecting GitHub status check results.

Values: info, warning, error

Control GitHub status check behavior:

Level	GitHub Status
`info`	neutral
`warning`	neutral
`error`	failure

Default: info

`filter_mode`

Filtering mode for the reviewdog command.

Values: added, diff_context, file, nofilter

See the reviewdog filter-mode documentation for detailed explanations of when to use each filtering mode.

Default: added

`fail_level`

Determines when reviewdog exits with a non-zero code, failing the workflow.

Values: none, any, info, warning, error

By default (none), reviewdog exits with code 0 even when violations exist. Set this to fail your workflow when violations at or above the specified severity level are found.

Default: none

`reviewdog_flags`

Additional reviewdog flags.

Default: ''

Contributing

Contributions are welcome! Please see our Contributing Guide for details on how to:

Report bugs and request features
Submit pull requests
Follow our code of conduct

We follow the Contributor Covenant Code of Conduct.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Name		Name	Last commit message	Last commit date
Latest commit History 531 Commits
.github		.github
testdata		testdata
.editorconfig		.editorconfig
.gitattributes		.gitattributes
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
.trivyignore		.trivyignore
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
action.yml		action.yml
entrypoint.sh		entrypoint.sh

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Java Checkstyle Reviewer (GitHub Action)

Features

Quick Start

Table of Contents

Example

Usage

Security Note: Pin by Tag or by Hash?

Pinning by Tag

Pinning by Commit SHA

Best Practice

Required Permissions

Input Parameters

Checkstyle Parameters

`checkstyle_config`

`checkstyle_version`

`workdir`

`properties_file`

`exclude`

Reviewdog Parameters

`github_token`

`reporter`

`level`

`filter_mode`

`fail_level`

`reviewdog_flags`

Contributing

License

About

Uh oh!

Releases 113

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

Java Checkstyle Reviewer (GitHub Action)

Features

Quick Start

Table of Contents

Example

Usage

Security Note: Pin by Tag or by Hash?

Pinning by Tag

Pinning by Commit SHA

Best Practice

Required Permissions

Input Parameters

Checkstyle Parameters

checkstyle_config

checkstyle_version

workdir

properties_file

exclude

Reviewdog Parameters

github_token

reporter

level

filter_mode

fail_level

reviewdog_flags

Contributing

License

About

Topics

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 113

Uh oh!

Contributors

Uh oh!

Languages

`checkstyle_config`

`checkstyle_version`

`workdir`

`properties_file`

`exclude`

`github_token`

`reporter`

`level`

`filter_mode`

`fail_level`

`reviewdog_flags`