Skip to content

permissions.md

Latest commit

 

History

History
117 lines (81 loc) · 3.91 KB

permissions.md

File metadata and controls

117 lines (81 loc) · 3.91 KB
Raw

Token Permissions

This is an exhaustive list of required permissions organized by features.

!!! info "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`](https://docs.github.com/en/actions/reference/authentication-in-a-workflow)

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:

=== "#!yaml on: push"

For [push events](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#push)

```yaml
    permissions:
      contents: read # (1)!
```

1. This permission is also needed to download files if the repository is not
   checked out before running cpp-linter.

=== "#!yaml on: pull_request"

For [pull_request events](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#pull_request)

```yaml
    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 `#!yaml write` is also sufficient as that is required for

    * posting [thread comments](#thread-comments) on pull requests
    * posting [pull request reviews](#pull-request-reviews)

Thread Comments

The thread-comments feature requires the following permissions:

=== "#!yaml on: push"

For [push events](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#push)

```yaml
    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.

=== "#!yaml on: pull_request"

For [pull_request events](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#pull_request)

```yaml
    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 to commit and push the formatted changes back to the PR branch.

!!! warning "CI re-triggering with auto-fix"

The default `GITHUB_TOKEN` **cannot** trigger new CI runs when pushing
a commit. If you need the auto-fix commit to trigger CI checks
(e.g. to verify the fix builds clean), use a personal access token
(PAT) with `contents: write` scope:

```yaml
- uses: actions/checkout@v7
  with:
    token: ${{ secrets.MY_PAT }}
```

When using the default `GITHUB_TOKEN`, you can include `[skip ci]` in
the auto-fix commit message to avoid unnecessary CI runs on the
fix commit itself. See the [`auto-fix-commit-msg`](./inputs-outputs.md#auto-fix-commit-msg) input.

!!! warning "Pull requests from third-party forks"

Auto-fix does not work on pull requests from third-party forks. The
`GITHUB_TOKEN` lacks write permission to the fork repository, and
`git push` to the fork's branch is not possible. Consider
restricting `auto-fix` to `push` events or pull requests from the
same repository.