From 2304bb712726db0a3c80de9c16d6acdc85dcddb6 Mon Sep 17 00:00:00 2001 From: Xianpeng Shen Date: Sat, 26 Sep 2026 22:56:46 +0300 Subject: [PATCH 1/3] docs: fix the usage example and the list of users - The usage example posts a thread comment but set no permissions, so it failed on repositories whose token is read-only by default and on pull requests from forks. It now sets `pull-requests: write` and skips the comment on pull requests from forks. - The auto-fix tip suggested putting a skip-CI marker in `auto-fix-commit-msg`. On the pull request head that leaves required checks pending, and a squash merge can carry it to the default branch. The tip, and docs/permissions.md, now warn against it. - Used By lists only organizations whose default branch still runs the action. Microsoft, NASA, TheAlgorithms and imgproxy are removed: no Microsoft or imgproxy repository uses it, nasa/CryptoLib switched to another action in March 2025, and TheAlgorithms/C-Plus-Plus went back to its own clang-tidy step. - actions/checkout is v7 in the usage example and the recipes, as in the auto-fix example. --- .../workflows/examples/only-PR-comments.yml | 2 +- .../workflows/examples/only-clang-format.yml | 2 +- .../workflows/examples/only-clang-tidy.yml | 2 +- README.md | 48 +++++++++---------- docs/permissions.md | 7 +-- 5 files changed, 30 insertions(+), 31 deletions(-) diff --git a/.github/workflows/examples/only-PR-comments.yml b/.github/workflows/examples/only-PR-comments.yml index d4771330..22505633 100644 --- a/.github/workflows/examples/only-PR-comments.yml +++ b/.github/workflows/examples/only-PR-comments.yml @@ -13,7 +13,7 @@ jobs: permissions: # (1)! pull-requests: write steps: - - uses: actions/checkout@v5 + - uses: actions/checkout@v7 # ... optionally setup build env to create a compilation database diff --git a/.github/workflows/examples/only-clang-format.yml b/.github/workflows/examples/only-clang-format.yml index c7450d82..24c0d4c9 100644 --- a/.github/workflows/examples/only-clang-format.yml +++ b/.github/workflows/examples/only-clang-format.yml @@ -11,7 +11,7 @@ jobs: cpp-linter: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v5 + - uses: actions/checkout@v7 # ... optionally setup build env to create a compilation database diff --git a/.github/workflows/examples/only-clang-tidy.yml b/.github/workflows/examples/only-clang-tidy.yml index e673e44b..136cc561 100644 --- a/.github/workflows/examples/only-clang-tidy.yml +++ b/.github/workflows/examples/only-clang-tidy.yml @@ -11,7 +11,7 @@ jobs: cpp-linter: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v5 + - uses: actions/checkout@v7 # ... optionally setup build env to create a compilation database diff --git a/README.md b/README.md index 2ffe562f..2493d732 100644 --- a/README.md +++ b/README.md @@ -48,8 +48,17 @@ Create a new GitHub Actions workflow in your project, e.g. at [.github/workflows The content of the file should be in the following format. ```yaml +name: cpp-linter +on: pull_request + +jobs: + cpp-linter: + runs-on: ubuntu-latest + permissions: + contents: read + pull-requests: write # to post the thread comment steps: - - uses: actions/checkout@v5 + - uses: actions/checkout@v7 - uses: cpp-linter/cpp-linter-action@v2 id: linter env: @@ -58,7 +67,8 @@ The content of the file should be in the following format. 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' }} + # 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' }} - name: Fail fast?! if: steps.linter.outputs.checks-failed > 0 run: exit 1 @@ -92,14 +102,11 @@ 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][app-token-doc]. To keep a particular -> auto-fix commit from re-running CI, add `[skip ci]` to its message: +> the action with a [GitHub App token][app-token-doc]. > -> ```yaml -> with: -> auto-fix: 'true' -> auto-fix-commit-msg: 'style: apply clang-format fixes [skip ci]' -> ``` +> Do not add `[skip ci]` to `auto-fix-commit-msg`. The auto-fix commit becomes the +> head of the pull request, so its required checks would stay pending and block the +> merge, and a squash merge can carry the marker into your default branch. > > See [our documented permissions][permissions-doc] for the required scopes. @@ -116,38 +123,29 @@ See [GitHub App token][app-token-doc] for the setup steps. ## Used By

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

diff --git a/docs/permissions.md b/docs/permissions.md index b50c373a..8bd121ea 100644 --- a/docs/permissions.md +++ b/docs/permissions.md @@ -106,9 +106,10 @@ in addition to any other permissions needed for other features: 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, push with a [GitHub App token](#github-app-token) or a personal access token - that has `contents: write`; add `[skip ci]` to - [`auto-fix-commit-msg`](./inputs-outputs.md#auto-fix-commit-msg) if a - particular auto-fix commit should not start a run. + that has `contents: write`. Do not add `[skip ci]` to + [`auto-fix-commit-msg`](./inputs-outputs.md#auto-fix-commit-msg): the + auto-fix commit becomes the head of the pull request, so its required + checks would stay pending and block the merge. Pull requests from forks are skipped with a warning: `GITHUB_TOKEN` cannot push to the fork's branch, and fork pull requests receive no secrets, so an From 4fbedaed3d573212af031ccbeae4268d6bf2b2f3 Mon Sep 17 00:00:00 2001 From: Xianpeng Shen Date: Sun, 27 Sep 2026 09:49:57 +0300 Subject: [PATCH 2/3] Apply batched suggestions from code review Co-authored-by: Brendan <2bndy5@gmail.com> --- docs/permissions.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/permissions.md b/docs/permissions.md index 8bd121ea..191d7253 100644 --- a/docs/permissions.md +++ b/docs/permissions.md @@ -109,7 +109,8 @@ in addition to any other permissions needed for other features: that has `contents: write`. Do not add `[skip ci]` to [`auto-fix-commit-msg`](./inputs-outputs.md#auto-fix-commit-msg): the auto-fix commit becomes the head of the pull request, so its required - checks would stay pending and block the merge. + checks skipped for `push` or `pull_request` events would stay + pending and may cause loss of quality control. Pull requests from forks are skipped with a warning: `GITHUB_TOKEN` cannot push to the fork's branch, and fork pull requests receive no secrets, so an From 574a2dd79237a03e510ae2b77361abb27a6112b1 Mon Sep 17 00:00:00 2001 From: Xianpeng Shen Date: Sun, 27 Sep 2026 10:39:40 +0300 Subject: [PATCH 3/3] docs: link GitHub's list of skip instructions The auto-fix warning named only one of the commit-message instructions that skip workflow runs. It now links GitHub's docs, which list all of them, and the README uses the wording from review, with "gap" instead of "loss". --- README.md | 9 ++++++--- docs/permissions.md | 7 ++++--- 2 files changed, 10 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 2493d732..94ce7525 100644 --- a/README.md +++ b/README.md @@ -10,6 +10,7 @@ [recipes-doc]: https://cpp-linter.github.io/cpp-linter-action/examples [permissions-doc]: https://cpp-linter.github.io/cpp-linter-action/permissions [app-token-doc]: https://cpp-linter.github.io/cpp-linter-action/permissions/#github-app-token +[skip-doc]: https://docs.github.com/en/actions/how-tos/manage-workflow-runs/skip-workflow-runs [format-annotations-preview]: https://raw.githubusercontent.com/cpp-linter/cpp-linter-action/main/docs/images/annotations-clang-format.png [tidy-annotations-preview]: https://raw.githubusercontent.com/cpp-linter/cpp-linter-action/main/docs/images/annotations-clang-tidy.png @@ -104,9 +105,11 @@ the workspace to the pull request's head commit before it lints and commits. > so CI does not re-check the auto-fix commit. To change that, check out and run > the action with a [GitHub App token][app-token-doc]. > -> Do not add `[skip ci]` to `auto-fix-commit-msg`. The auto-fix commit becomes the -> head of the pull request, so its required checks would stay pending and block the -> merge, and a squash merge can carry the marker into your default branch. +> Do not add `[skip ci]` or any other [skip instruction][skip-doc] 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][permissions-doc] for the required scopes. diff --git a/docs/permissions.md b/docs/permissions.md index 191d7253..b6a54791 100644 --- a/docs/permissions.md +++ b/docs/permissions.md @@ -106,11 +106,12 @@ in addition to any other permissions needed for other features: 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, push with a [GitHub App token](#github-app-token) or a personal access token - that has `contents: write`. Do not add `[skip ci]` to - [`auto-fix-commit-msg`](./inputs-outputs.md#auto-fix-commit-msg): the + that has `contents: write`. Do not add `[skip ci]` or any other + [skip instruction](https://docs.github.com/en/actions/how-tos/manage-workflow-runs/skip-workflow-runs) + to [`auto-fix-commit-msg`](./inputs-outputs.md#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 loss of quality control. + pending and may cause a gap in quality control. Pull requests from forks are skipped with a warning: `GITHUB_TOKEN` cannot push to the fork's branch, and fork pull requests receive no secrets, so an