Token Permissions¶
This is an exhaustive list of required permissions organized by features.
Important
The GITHUB_TOKEN environment variable should be supplied when running on a private repository.
Otherwise the runner does not not have the privileges needed for the features mentioned here.
See also Authenticating with the GITHUB_TOKEN
File Changes¶
When using files-changed-only or
lines-changed-only to get the list
of file changes for a CI event, the following permissions are needed:
For push events
permissions:
contents: read # (1)!
- This permission is also needed to download files if the repository is not checked out before running cpp-linter.
permissions:
contents: read # (1)!
pull-requests: read # (2)!
- For pull requests, this permission is only needed to download files if the repository is not checked out before running cpp-linter.
-
Specifying
writeis also sufficient as that is required for- posting thread comments on pull requests
- posting pull request reviews
Thread Comments¶
The thread-comments feature requires the following permissions:
For push events
permissions:
contents: write # (1)!
- needed to fetch existing comments and to post or update a commit comment. This also allows us to delete an outdated comment if needed.
permissions:
pull-requests: write
Pull Request Reviews¶
The tidy-review, format-review, and passive-reviews features require the following permissions:
permissions:
pull-requests: write
Pull requests from forks¶
GitHub gives a pull request from a fork a read-only GITHUB_TOKEN, whatever the
permissions of the workflow say, unless a private or internal repository turns on
Send write tokens to workflows from pull requests. File annotations, the step summary
and the outputs still work. thread-comments and the
pull request reviews need pull-requests: write, so they are not posted, and the log shows
403 Resource not accessible by integration.
To comment on those pull requests too, split the work into two workflows: one lints with
the read-only token and uploads the comment as an artifact, the other runs on
workflow_run with pull-requests: write and posts it. See the
PR comments from forks recipe.
Do not lint pull requests in pull_request_target
pull_request_target runs with a write token and the repository's secrets. If that
workflow checks out the pull request's code and builds it, for example to create a
compilation database with CMake, code from the pull request runs with that token.
Lint in pull_request, and post the comment from workflow_run.
From December 2, 2026, GitHub
blocks pull_request_target by default
in public repositories: such workflows do not run unless an Actions policy allows the
event. A workflow that posts cpp-linter comments that way stops commenting on that date.
The recipe above does not use pull_request_target.
Auto-fix¶
The auto-fix feature requires contents: write permission
in addition to any other permissions needed for other features:
permissions:
contents: write # (1)!
- Needed by the token used in
actions/checkoutto commit and push the formatted changes back to the branch.
The action checks out the pull request head
On pull_request events actions/checkout provides the merge commit
(refs/pull/N/merge), not the branch. A commit made on it would carry that
merge into the pull request, so with auto-fix the action checks out the
pull request's head commit before it lints. Steps that run after the action
see that commit plus the auto-fix commit. If git refuses the checkout
because of local changes, auto-fix is skipped with a warning.
Limits
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 or a personal access token
that has contents: write. 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.
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
App token or PAT is not available there either. They are skipped on
pull_request_target as well, where the token could push, but only to this
repository.
On events that carry no pull request (issue_comment, workflow_run,
schedule, workflow_dispatch), the fix is pushed to the branch the
workflow runs for, which is usually the default branch. So it is only
committed when the checked out commit is the one that triggered the
workflow (GITHUB_SHA). If the workflow checked out another commit, for
example a pull request's head, auto-fix is skipped with a warning.
Otherwise that pull request's commits would land on the default branch.
GitHub App token¶
A token minted from a GitHub App you own replaces the default GITHUB_TOKEN
for every feature on this page. Pushes made with it start workflow runs, and
comments and reviews are posted under the App's name instead of
github-actions[bot].
- Register a GitHub App with the repository permissions Contents: Read and write and Pull requests: Read and write, then install it on the repository.
- Store the App ID as a repository variable and the private key as a secret.
- Mint the token at the start of the job and pass it to both
actions/checkoutand cpp-linter:
steps:
- uses: actions/create-github-app-token@v3
id: app-token
with:
app-id: ${{ vars.CPP_LINTER_APP_ID }}
private-key: ${{ secrets.CPP_LINTER_APP_PRIVATE_KEY }}
- uses: actions/checkout@v7
with:
token: ${{ steps.app-token.outputs.token }} # (1)!
- uses: cpp-linter/cpp-linter-action@v2
env:
GITHUB_TOKEN: ${{ steps.app-token.outputs.token }} # (2)!
with:
style: 'file'
auto-fix: 'true'
- The auto-fix commit is pushed with this token, so the push triggers your other workflows.
- Thread comments and pull request reviews are posted with this token.
The job's permissions block only applies to GITHUB_TOKEN; the App token's
permissions come from the App's settings.