Checkstyle for Java GitHub Action

Enforce Java code quality standards in your pull requests with automated Checkstyle analysis.
Powered by reviewdog, this action reports violations directly in your PR reviews, making it easy to maintain consistent code style across your team.

Features

• Zero Configuration - Works out of the box with Google or Sun coding conventions
• Flexible Reporting - Choose between PR comments, checks, or reviews
• Version Control - Pin to any Checkstyle version for consistency
• Custom Rules - Use your own Checkstyle configuration files
• Smart Filtering - Only review changed lines or entire files
• GitHub Integration - Native support for GitHub 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.

Table of Contents

• Features
• Quick Start
• Example
• Usage
  • Security Note: Pin by Tag or by Hash?
• Input Parameters
  • Checkstyle Parameters
    • checkstyle_config
    • checkstyle_version
    • workdir
    • properties_file
  • Reviewdog Parameters
    • github_token
    • reporter
    • level
    • filter_mode
    • fail_level
    • reviewdog_flags
• Contributing
• License

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/[email protected] # 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.

Input Parameters

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:

  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
            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:

  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
            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:

  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
            checkstyle_config: ./properties_file/test_checks.xml
            properties_file: ./properties_file/additional.properties

  Example PR demonstrating properties file usage with custom configuration

Reviewdog Parameters

• github_token

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

  Use the automatically provided secrets.github_token or secrets.GITHUB_TOKEN in your workflow. This token is automatically created by GitHub for each workflow run with appropriate permissions.

  Note: For the github-pr-review and github-pr-check reporters to work properly, ensure your workflow has pull-requests: write permission. This is granted by default in most cases.

  Required: Yes

  Example:

  - uses: dbelyaev/action-checkstyle@v3
    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.