Suggest changes

This GitHub Action takes changes from the working directory (using git diff) and applies them as suggested changes in a pull request review. This can be useful after running a linter or formatter that automatically makes fixes for you.

• Gives contributors an opportunity to review and accept automated changes.
• Enables semi-automated changes to pull requests without needing to use a personal access token (PAT) or GitHub App installation token to trigger workflow runs.

Quickstart

Add this step to your workflow after a step that modifies files:

- uses: parkerbxyz/suggest-changes@v3

Important

This GitHub Action works on pull_request and pull_request_target events.

Usage

Basic example

Here's a minimal example showing how to use this action:

on:
  pull_request:

permissions:
  contents: read # Needed for actions/checkout
  pull-requests: write # Needed for this action

jobs:
  suggest-changes:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5

      # Make some changes to files here
      # (e.g., run a linter or formatter)

      - uses: parkerbxyz/suggest-changes@v3

Complete example

Here's a complete workflow that runs markdownlint and suggests changes when fixes are made:

name: 'markdownlint'

on:
  pull_request:
    paths: ['**/*.md']

permissions:
  contents: read # Needed for actions/checkout
  pull-requests: write # Needed for this action

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5

      - uses: DavidAnson/markdownlint-cli2-action@v20
        id: markdownlint
        with:
          fix: true
          globs: '**/*.md'

      # Check if markdownlint made any fixes
      - uses: tj-actions/verify-changed-files@v20
        id: verify-changed-files
        if: always() && steps.markdownlint.outcome != 'skipped'
        with:
          # Fail if files were changed (this indicates there are linting errors to fix)
          fail-if-changed: 'true'

      # Suggest fixes if any were made
      - uses: parkerbxyz/suggest-changes@v3
        if: failure() && steps.verify-changed-files.outcome == 'failure'
        with:
          comment: 'Please commit the suggested changes from markdownlint.'
          event: 'REQUEST_CHANGES'

Inputs

All inputs are optional.

comment

Default: none

The pull request review comment that will be displayed at the top of the review.

event

Default: COMMENT

The review action to perform. Options: APPROVE, REQUEST_CHANGES, or COMMENT.

Note

Using REQUEST_CHANGES will block the pull request from being merged until the review is dismissed or the same reviewer approves the changes.

token

Default: ${{ github.token }}

Access token to make authenticated API calls. When using the default GITHUB_TOKEN, ensure the pull-requests: write permission is set in your workflow.

Pull requests from forks

The default GITHUB_TOKEN has read-only permissions for pull requests from forks and cannot create review comments. There are two solutions:

Option 1: Use a GitHub App token (recommended)

The pull_request event is recommended for most use cases. When triggered from a fork, the workflow runs in the fork's context, which is more secure than pull_request_target. You can use a GitHub App token to provide the necessary permissions:

on:
  pull_request:

jobs:
  suggest-changes:
    runs-on: ubuntu-latest
    permissions:
      contents: read # Needed for actions/checkout
    steps:
      - uses: actions/checkout@v5

      # Run your linter or formatter here
      # Example: markdownlint, prettier, eslint --fix, etc.

      - name: Generate token
        id: generate-token
        uses: actions/create-github-app-token@v2
        with:
          app-id: ${{ vars.APP_ID }}
          private-key: ${{ secrets.APP_PRIVATE_KEY }}

      - name: Suggest changes
        uses: parkerbxyz/suggest-changes@v3
        with:
          token: ${{ steps.generate-token.outputs.token }}
          comment: 'Please commit the suggested changes.'

Option 2: Use pull_request_target event

The pull_request_target event can be used to support pull requests from forks, as it grants the GITHUB_TOKEN write permissions even when triggered from a fork.

Caution

When using pull_request_target, the workflow runs in the context of the base repository. Running untrusted code from a pull request in this context can lead to security vulnerabilities including repository compromise and secret exposure. For more information, see pull_request_target and Mitigating the risks of untrusted code checkout.

Limitations

Limitations due to GitHub API and platform constraints:

• Suggested changes can only be applied to files and lines that are part of the pull request diff.
• Suggested changes are limited to 3000 files per pull request.
• GitHub currently limits each review to 100 comments. If your changes generate more than 100 suggestions, this action will post the first 100 suggestions and explain that additional suggestions may be posted on future workflow runs.
• GitHub enforces API rate limits. If rate limits are exceeded, the action will log a warning with the reset time when available and stop processing.