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.

• 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

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.

• Features
• Quick Start
• Example
• Usage
  • Security Note: Pin by Tag or by Hash?
• 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

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

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

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

- 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

- 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

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.

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

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.

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

Checkstyle inputs:

Reviewdog inputs:

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

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

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

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

Default: '.' (root)

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

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

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.

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

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

Values: info, warning, error

Control GitHub status check behavior:

Default: info

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

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

Additional reviewdog flags.

Default: ''

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.

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