Skip to content

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)!
  1. This permission is also needed to download files if the repository is not checked out before running cpp-linter.

For pull_request events

    permissions:
      contents: read # (1)!
      pull-requests: read # (2)!
  1. For pull requests, this permission is only needed to download files if the repository is not checked out before running cpp-linter.
  2. Specifying write is also sufficient as that is required for

Thread Comments

The thread-comments feature requires the following permissions:

For push events

    permissions:
      contents: write # (1)!
  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.

For pull_request events

    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)!
  1. Needed by the token used in actions/checkout to 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].

  1. Register a GitHub App with the repository permissions Contents: Read and write and Pull requests: Read and write, then install it on the repository.
  2. Store the App ID as a repository variable and the private key as a secret.
  3. Mint the token at the start of the job and pass it to both actions/checkout and 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'
  1. The auto-fix commit is pushed with this token, so the push triggers your other workflows.
  2. 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.