Submit a Careful Pull Request Review with gh pr review

You will finish with a repeatable way to submit a comment, approval, or change request on a GitHub pull request from the shell. The examples use GitHub CLI 2.87.3, installed here as package gh. Allow about ten minutes for a review you have already inspected. You need an authenticated GitHub CLI session, permission to review the repository, and the pull request number, URL, or branch.

This command submits a real review. There is no dry-run flag in the installed command's interface, and a submitted review changes the pull request. Read the body and action carefully before pressing Enter. Do not use these examples as a way to test credentials against a production repository.

1. Confirm the installed command

Start with a read-only help check. It needs no elevated privileges and does not contact a repository:

$ gh --version
gh version 2.87.3 (2026-02-23)
$ gh pr review --help
Add a review to a pull request.

The relevant syntax is gh pr review [number | URL | branch] [flags]. The installed manual also says that omitting the argument selects the pull request belonging to the current branch. That default is convenient, but it is an easy source of mistakes if your checkout is not on the branch you think it is.

Checkpoint: if the version or help output differs materially, stop and read the local help again. Do not assume another release accepts the same flags.

2. Identify the exact pull request

Prefer an explicit pull request number or URL when the review matters. A number is interpreted in the repository selected by your current checkout or by --repo:

$ gh pr review 123 --repo OWNER/REPOSITORY --comment --body "Please add a regression test for the timeout path."

Do not run that example yet. It is shown to make the final command shape clear, and it would submit a review. Replace 123, OWNER/REPOSITORY, and the body with values you have checked. The inherited -R or --repo option accepts [HOST/]OWNER/REPO, so include a host only when your GitHub CLI setup uses one.

If you use the current branch instead, inspect the branch and repository with ordinary Git and then keep the command's omitted argument in mind:

$ git branch --show-current
feature/example
$ git remote -v
origin  [email protected]:OWNER/REPOSITORY.git (fetch)

A branch name can select a pull request, but the manpage does not promise what happens when several pull requests match or when no pull request belongs to it. An explicit number or URL removes that ambiguity.

3. Choose exactly one review action

The command provides three mutually distinct actions:

• --comment submits a review comment without approving or requesting changes.
• --approve approves the pull request.
• --request-changes requests changes on the pull request.

Keep the action visible in the command. Do not copy a command from a previous review and change only the body. An approval and a change request carry different meaning, and the short forms -a, -c, and -r are easy to confuse when scanning a shell history.

Before submitting an approval or a change request, check the repository's review policy and your own findings. These actions may affect merge eligibility or the work expected from another contributor. No elevated privileges are needed, and sudo cannot repair a missing GitHub permission.

4. Submit a short inline body

Use --body or -b for a short, already-written message. This example submits a comment to pull request 123:

$ gh pr review 123 --repo OWNER/REPOSITORY --comment --body "Please add a regression test for the timeout path."

Shell quoting is part of the safety check. Double quotes preserve spaces, but shell expansion still happens inside them. Use single quotes for ordinary text containing a dollar sign, or prepare the message in a file when it contains several lines. Never interpolate untrusted issue text or a generated command directly into the body without checking what the shell will expand.

Successful output and its exact wording can vary by GitHub CLI release and server. Treat a returned shell prompt alone as insufficient evidence. Check the pull request in the GitHub interface or with the repository's normal review workflow, and confirm that the new review has the intended action and body.

5. Submit a multi-line body from a file

For a longer review, write the text in a temporary file and inspect it before submission. This keeps shell quoting out of the review message:

$ cat > /tmp/pr-review.txt
The change is close. Please add a regression test for the timeout path.

Once that test passes, this comment should be ready to resolve.
^D
$ sed -n '1,20p' /tmp/pr-review.txt
The change is close. Please add a regression test for the timeout path.

Once that test passes, this comment should be ready to resolve.
$ gh pr review 123 --repo OWNER/REPOSITORY --comment --body-file /tmp/pr-review.txt

The --body-file option reads the review body from the named file. The manual also supports - to read from standard input, but a file gives you a visible checkpoint before the state-changing command. The cat command above creates or truncates /tmp/pr-review.txt; use another path if that file contains something you need. After confirming the review is present, remove only this temporary file if it contains sensitive material:

$ rm -- /tmp/pr-review.txt

That removal is local and irreversible. It does not remove the submitted review from GitHub. If you discover an error after submission, do not assume the CLI has an undo operation. Check the review on GitHub and follow the repository's correction process, such as a follow-up review or a maintainer-led resolution.

6. Approve or request changes only after the final check

Once the body, repository and pull request number are confirmed, use the corresponding action. These commands submit state-changing reviews:

$ gh pr review 123 --repo OWNER/REPOSITORY --approve --body "The requested tests pass and the implementation looks ready."
$ gh pr review 123 --repo OWNER/REPOSITORY --request-changes --body "Please handle the timeout error before merging."

Run only one of the two lines. The examples are alternatives, not a sequence. If you need a neutral observation, use --comment instead. If you are unsure which action reflects your review, stop before running the command and resolve that uncertainty with the repository's normal process.

After submission, verify the pull request number, review type and message on GitHub. If the command reports an authentication, permission, repository or network error, treat the review as unconfirmed until the pull request itself shows it. Retrying can create an additional review when the first request actually succeeded but the response was lost.

7. Keep the boundary clear

gh pr review adds a review to an existing pull request. It does not create a pull request, change files, merge code, or alter local Git history. The command's available options are limited to selecting the review action and body, plus the inherited repository selector. Do not expect --approve to merge anything, and do not treat a successful review as proof that automated checks passed.

For scripts, pass a fixed pull request identifier and a fixed body file, then record the command's exit status and verify the remote review. Avoid putting secrets, access tokens or private incident details in a review body. A review is visible to the people who can access that repository and may be retained in its audit history.