cpp-linter-action

A GitHub Action that checks the C and C++ files a pull request changes with clang-format and clang-tidy, and reports the findings as file-annotations, thread-comments, a workflow step-summary and pull request reviews (with tidy-review or format-review).

Website · Documentation · Marketplace · Get started · Discussions

Quick start

Save this as .github/workflows/cpp-linter.yml:

name: cpp-linter
on: pull_request

jobs:
  cpp-linter:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
    steps:
      - uses: actions/checkout@v7
      - uses: cpp-linter/cpp-linter-action@v2
        id: linter
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        with:
          version: '21'
          style: file
          tidy-checks: ''
          format-review: true
      - name: Fail on lint errors
        if: steps.linter.outputs.checks-failed > 0
        run: exit 1

• style: file and tidy-checks: '' use your .clang-format and .clang-tidy. version takes an LLVM major from 12 to 23; 21 is the default.
• Annotations in the diff view are on by default. format-review, tidy-review and thread-comments are opt-in and need pull-requests: write; turn on one of the two reviews, not both. auto-fix commits the clang-format fixes to the branch and needs contents: write.
• The action does not fail the job by itself; the last step does, using the checks-failed output.
• Pull requests from forks get a read-only token: annotations still appear, but reviews are not posted, and thread-comments would fail the step. Draft pull requests get no review.

Usage

For all explanations of our available input parameters and output variables, see our Inputs and Outputs document.

See also our example recipes.

Post a thread comment

Set thread-comments to post the findings as a comment in the pull request thread. With update, the action updates its existing comment instead of posting a new one:

      - uses: cpp-linter/cpp-linter-action@v2
        id: linter
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        with:
          style: 'file'  # Use .clang-format config file
          tidy-checks: '' # Use .clang-tidy config file
          # only 'update' a single comment in a pull request thread.
          # Pull requests from forks get a read-only token, so skip the comment there.
          thread-comments: ${{ github.event.pull_request.head.repo.full_name == github.repository && 'update' }}

Auto-fix clang-format issues

Set auto-fix: 'true' and the action applies clang-format -i to the files with style issues and commits the result to the branch:

    steps:
      - uses: actions/checkout@v7
      - uses: cpp-linter/cpp-linter-action@v2
        id: linter
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        with:
          style: 'file'
          auto-fix: 'true'  # automatically fix format issues

On pull_request events actions/checkout checks out the merge commit, so the action switches the workspace to the pull request's head commit before it lints and commits.

Tip

Commits pushed with the default GITHUB_TOKEN do not start new workflow runs, so CI does not re-check the auto-fix commit. To change that, check out and run the action with a GitHub App token.

Do not add [skip ci] or any other skip instruction to auto-fix-commit-msg. The auto-fix commit becomes the head of the pull request, so its required checks skipped for push or pull_request events would stay pending and may cause a gap in quality control. A squash merge can also carry the instruction into your default branch.

See our documented permissions for the required scopes.

Use your own GitHub App

Every feature above can run with a token minted from a GitHub App that you own instead of the default GITHUB_TOKEN. Comments and reviews are then posted under your App's name rather than github-actions[bot], and commits pushed by auto-fix do start new workflow runs. The token is minted inside the job, so there is no server or webhook handling to host.

See GitHub App token for the setup steps.

Example

Annotations

Using file-annotations:

clang-format annotations

clang-tidy annotations

Thread Comment

Using thread-comments:

Step Summary

Using step-summary:

Pull Request Review

Only clang-tidy

Using tidy-review:

Only clang-format

Using format-review:

Supported runners

Linux, macOS and Windows runners are supported. On Linux, we only support a Debian-based Linux OS (like Ubuntu and many others), because we first try to use the apt package manager to install clang tools. Linux workflows that use a specific container need a few packages installed first. Required tools lists them and the sources each runner installs the clang tools from.

Used by

Projects from these organizations run cpp-linter-action on their default branch:

Apache · Samsung · Bloomberg · Qualcomm · Nextcloud · CachyOS · Jupyter Xeus · NNStreamer · Zondax · AppNeta · Chocolate Doom

The showcase lists more projects that use it.

Contributing

Read CONTRIBUTING.md before you open a pull request, and report bugs or request features in issues.

License

The scripts and documentation in this project are released under the MIT License