C/C++ Linter Action _{^{| clang-format & clang-tidy}}

A Github Action for linting C/C++ code integrating clang-tidy and clang-format to collect feedback provided in the form of file-annotations, thread-comments, workflow step-summary, and Pull Request reviews (with tidy-review or format-review).

Tip

Prefer pre-commit hooks over GitHub Actions? Check out cpp-linter-hooks — a pre-commit hook repository that runs clang-format and clang-tidy consistently on developer machines and in CI, with no manual LLVM installs.

Usage

Create a new GitHub Actions workflow in your project, e.g. at .github/workflows/cpp-linter.yml

The content of the file should be in the following format.

    steps:
      - uses: actions/checkout@v5
      - 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.
          thread-comments: ${{ github.event_name == 'pull_request' && 'update' }}
      - name: Fail fast?!
        if: steps.linter.outputs.checks-failed > 0
        run: exit 1

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

See also our example recipes.

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. To keep a particular auto-fix commit from re-running CI, add [skip ci] to its message:

    with:
      auto-fix: 'true'
      auto-fix-commit-msg: 'style: apply clang-format fixes [skip ci]'

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.

Used By

Microsoft   Apache   NASA   Samsung   TheAlgorithms   CachyOS  
Nextcloud   Jupyter   NNStreamer   imgproxy   Zondax   AppNeta  
Chocolate Doom Bloomberg Qualcomm and many more.

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:

Add C/C++ Linter Action badge in README

You can show C/C++ Linter Action status with a badge in your repository README

Example

[![cpp-linter](https://github.com/cpp-linter/cpp-linter-action/actions/workflows/cpp-linter.yml/badge.svg)](https://github.com/cpp-linter/cpp-linter-action/actions/workflows/cpp-linter.yml)

Have question or feedback?

To provide feedback (requesting a feature or reporting a bug) please post to issues.

Required tools installed

As of v2.16.0, this action uses

• nushell for cross-platform compatible scripting
• uv for driving a Python virtual environment

This action installs nushell and uv automatically. Only nushell is added to the PATH environment variable. uv, and any standalone Python distribution it downloads, are not added to the PATH environment variable.

On Linux runners

We only support Linux runners using a Debian-based Linux OS (like Ubuntu and many others). This is because we first try to use the apt package manager to install clang tools.

Linux workflows that use a specific container should ensure that the following are installed:

• GLIBC (v2.32 or later)
• wget or curl
• lsb-release (required by LLVM-provided install script)
• software-properties-common (required by LLVM-provided install script)
• gnupg (required by LLVM-provided install script)

apt-get update
apt-get install -y libc6 wget lsb-release software-properties-common gnupg

Otherwise, nushell and/or the LLVM-provided bash script will fail to run.

If installing clang tools fails using the apt package manager, then we alternatively try the following sources in order:

1. PyPI Packages clang-tidy and/or clang-format
2. Static binaries that we built ourselves; see cpp-linter/clang-tools-pip project for more detail.

On macOS runners

The specified version of clang-format and clang-tidy is installed via the following sources in order (whichever succeeds first):

1. Homebrew
2. PyPI Packages clang-tidy and/or clang-format
3. Static binaries that we built ourselves; see cpp-linter/clang-tools-pip project for more detail.

On Windows runners

For Windows runners, we use clang tools installed via the following sources in order (whichever succeeds first):

1. PyPI Packages clang-tidy and/or clang-format
2. Static binaries that we built ourselves; see cpp-linter/clang-tools-pip project for more detail.

License

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