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:

on: pushon: pull_request

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

   • posting thread comments on pull requests
   • posting pull request reviews

Thread Comments

The thread-comments feature requires the following permissions:

on: pushon: pull_request

For push events

    permissions:
      metadata: read # (1)!
      contents: write # (2)!

1. needed to fetch existing comments
2. needed 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

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.

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.