docs: add guide on running clang-tidy on pull requests with GitHub Actions - #62
Merged
Merged
Conversation
✅ Deploy Preview for cpp-linter-github-io ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
shenxianpeng
added a commit
that referenced
this pull request
Sep 22, 2026
## Why cpp-linter-hooks already gets more Google traffic than the action (52 of its 288 repository views in the last 14 days came from Google, against 21 for cpp-linter-action), so people are searching for "clang-format pre-commit hook". The site has no page for that query. This is the second how-to written around a search term, after #62; the two PRs are independent. ## What's in this PR One new post in the Guides category: **Set up a clang-format pre-commit hook for C and C++** (`docs/blog/posts/2026-09-20-clang-format-pre-commit-hook.md`), published at `/blog/2026/09/20/clang-format-pre-commit-hook/` (explicit `slug`, plus a meta `description`). 1. A starter `.clang-format`. 2. Installing pre-commit and adding the hook; `rev` is the hook version, `--version` is the clang-format version (`21` resolves to the newest 21.x wheel, a full version pins it exactly). 3. What the first commit looks like, and why "Failed" means the files were fixed. 4. Formatting only your own code: `exclude`, a `DisableFormat` `.clang-format` in the vendored directory, and `types_or` for CUDA and Protobuf. 5. Existing code bases: reformat once with `.git-blame-ignore-revs`, or format as you go; `git clang-format` mentioned for changed-lines-only. 6. Enforcing the same configuration in CI with `pre-commit run --all-files --show-diff-on-failure`, or review suggestions from cpp-linter-action with `format-review`. 7. A troubleshooting table. 8. When to add the clang-tidy hook. ## Checks - Every command and output in the post was run in a scratch git repository with `rev: v1.6.0` and `--version=21` (resolved to clang-format 21.1.8): the blocked commit and the retry, `exclude`, the per-directory `DisableFormat`, `.cu` and `.proto` formatting via `types_or`, `SKIP=clang-format`, the CI output (pasted verbatim) and `blame.ignoreRevsFile`. - The compile database auto-detection mentioned in the last section was checked against `clang_tidy.py` at v1.6.0. - `mkdocs build --strict` passes locally, and the repository's pre-commit hooks pass on the new file. ## Notes - The post does not recommend `--dry-run`. With the released v1.6.0 the hook reports "Passed" for an unformatted file when `--dry-run` is set, with or without `--Werror`; the fix (cpp-linter/cpp-linter-hooks#257) is on `main` but not in a release yet. Once it is released, a check-only variant can be added to step 6. - There is no link to the clang-tidy guide from #62, because that page does not exist on `main` yet and the strict build would fail. The two posts can be cross-linked in a small follow-up once both are merged.
shenxianpeng
commented
Sep 29, 2026
shenxianpeng
force-pushed
the
docs/howto-clang-tidy-pull-requests
branch
from
September 29, 2026 16:08
41251fc to
1606c22
Compare
Contributor
|
It would be nice to also have some explanation about using third-party libs with clang-tidy because it often requires a compilation database to inform clang-tidy the |
Contributor
IIRC, the private repo support was dependent on the getting raw MD text in comments via HTTP response's JSON. I thought we fixed that by adding But recently, we had a user report failures to post thread comments on a private repo. I guess we could do a test run on a private repo in the cpp-linter org (or in a individual account's private repo). |
shenxianpeng
added a commit
that referenced
this pull request
Sep 30, 2026
…ate-repo claim (#72) Follows up on @2bndy5's comments on #62. **Third-party libraries in the clang-tidy guide.** Step 2 said to install dependencies before the configure step, but not why: clang-tidy finds a library's headers only through the `-I` paths the compiler gets for each file, which it reads from the compilation database. The bullet now says so, and shows how to pass those paths with `extra-args` when there is no build system (`-Ithird_party/fmt/include`, written without a space because `extra-args` splits on spaces). **Private repositories on the home page.** #70 said the step summary also works "in private repositories, where thread comments are turned off". That came from the note on `thread-comments` in cpp-linter-action's `action.yml`, but cpp-linter has no code that turns thread comments off for private repositories; its requests ask for `application/vnd.github.raw+json`, the change that addressed cpp-linter-action#142. As discussed on #62, whether thread comments work on a private repository still needs a test run, so the card no longer says anything about private repositories.
shenxianpeng
added a commit
to cpp-linter/cpp-linter-action
that referenced
this pull request
Sep 30, 2026
…sitories The `thread-comments` input said the feature is disabled on private repositories. cpp-linter has no such check any more: its requests ask for `application/vnd.github.raw+json`, which addressed #142, and nothing in `rest_api` looks at the repository's visibility. Following @2bndy5's suggestion on cpp-linter/cpp-linter.github.io#62, I ran the action on a private repository in the organization, cpp-linter/test-cpp-linter-action-private, with `thread-comments: update`: | Round | Push | Result | | --- | --- | --- | | 1 | code with one clang-format issue and two clang-tidy findings | github-actions[bot] posted one "Cpp-Linter Report" comment (run 36699441415) | | 2 | another function with findings | the same comment was edited (3 concerns); no second comment (run 36699583265) | | 3 | every finding fixed | the comment was deleted, as `no-lgtm: true` asks (run 36699719604) | All three runs passed, and their logs show no error from posting, editing or deleting the comment (the `##[warning]` lines are the file annotations for the findings). The workflow sets `permissions: pull-requests: write`; a repository whose default `GITHUB_TOKEN` is read-only needs that, as [documented](https://github.com/cpp-linter/cpp-linter-action/blob/main/docs/permissions.md). So the note is removed. The permissions note in `docs/permissions.md` (supply `GITHUB_TOKEN` on private repositories) stays; it is still true.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
People search for "clang-tidy github actions" and "clang-tidy pull request comments", and for those queries platisd/clang-tidy-pr-comments and ZedThree/clang-tidy-review rank ahead of cpp-linter-action. The site has no page that answers that question from start to finish; the two existing posts assume the reader already has a lint workflow. This is the first of a few how-to posts written around what people actually search for.
What's in this PR
One new post in the Guides category: Run clang-tidy on pull requests with GitHub Actions (
docs/blog/posts/2026-09-20-clang-tidy-pull-requests-github-actions.md), published at/blog/2026/09/20/clang-tidy-github-actions-pull-requests/(explicitslug, plus a metadescription).It follows the places where people get stuck:
.clang-tidy(bugprone-*,performance-*,clang-analyzer-*, explicitHeaderFilterRegex).compile_commands.jsonwith CMake, Meson, Make + Bear, orextra-argswhen there is no build system.files-changed-only/lines-changed-onlyand what each value reports.clang-tidy-checks-failedoutput, and rolling that out gradually.pull_request_target.Two details worth a look from someone who knows the action well:
tidy-checksvalue is appended to theChecksin.clang-tidy, and recommendstidy-checks: ''. That is taken from the input description inaction.yml.HeaderFilterRegexmatches. That is from the LLVM 22 release notes, and is the reason the starter config setsHeaderFilterRegexexplicitly.I left out the note about thread comments being disabled on private repositories, because I could not find the matching behaviour in the cpp-linter source.
Checks
action.ymlat v2.22.0,docs/permissions.mdanddocs/pr-review-caveats.md; the hook arguments against the cpp-linter-hooks README..clang-tidywas run with clang-tidy 22.1.0 on a small demo project:--verify-configreports no errors, a finding ininclude/is reported and the same finding inthird_party/is filtered out.mkdocs build --strictpasses locally, and the repository's pre-commit hooks pass on the new file.format-revieware gone, clang-format is off (style: ''),step-summaryis on, and the fail step usesclang-tidy-checks-failed.