Edit a Pull Request with gh pr edit

gh pr edit changes a pull request's title, body, labels, reviewers, assignees, projects or milestone from a shell, once you have checked the target. The examples use GitHub CLI 2.87.3, installed here as the gh package, and the local gh-pr-edit(1) manual dated March 2026.

Allow about ten minutes for a normal edit. You need gh, an authenticated GitHub account with permission to edit the pull request, and the repository name or a local branch that identifies it. These commands change remote pull request metadata immediately. They do not need sudo, and they do not touch commits in your local checkout.

Checkpoint: Keep the pull request number, intended new values and a copy of the old text on hand before running a command that changes state.

1. Confirm the installed command

Read the command's live help before copying an example. This is read-only:

$ gh --version
gh version 2.87.3 (2026-02-23)
$ gh pr edit --help

The command accepts a pull request number, URL or branch. With no argument, it selects the pull request belonging to the current branch, convenient, but also an easy way to edit the wrong request after switching branches. For automation and shared shell history, use an explicit number or URL.

The installed help is authoritative for this binary. The local manpage lists the core options, while this installed version also documents --remove-milestone, @copilot for reviewer and assignee operations, and attachment support. If a flag is missing from gh pr edit --help, do not assume the remote documentation applies to your installation.

2. Inspect the target before editing

Use gh pr view to record the current state. Replace the placeholder with a real number and repository:

$ gh pr view 123 --repo OWNER/REPOSITORY \
    --json number,title,body,baseRefName,headRefName,labels,assignees,reviewRequests,milestone,url

Review the output carefully, especially the repository, base branch and head branch. A pull request number is only unambiguous within a repository.

Checkpoint: Stop if the URL, branch names or current title are not the request you meant to edit. Save the current body somewhere safe if you are about to replace it.

3. Change a title or body

Pass a new title with --title and a new body with --body:

$ gh pr edit 123 --repo OWNER/REPOSITORY \
    --title 'Handle expired session tokens' \
    --body 'This change refreshes the session token before the API request.'

There is no merge, close or commit operation hidden in this command: it updates only the fields you specify. --body does replace the existing body, though, so do not use it to append a paragraph unless you have included the old content too.

For a longer body, put the exact text in a file and use --body-file. This avoids shell quoting mistakes and makes review possible:

$ ${EDITOR:-vi} /tmp/pr-123-body.txt
$ gh pr edit 123 --repo OWNER/REPOSITORY --body-file /tmp/pr-123-body.txt

Treat the file as sensitive if the body holds incident details, credentials or personal information. Do not put access tokens in the body or in a shell command copied into shared history.

4. Manage labels, reviewers and assignees

Each add or remove option takes a name or login. The examples shown by the command accept comma-separated values:

$ gh pr edit 123 --repo OWNER/REPOSITORY \
    --add-label 'bug,help wanted' \
    --remove-label 'needs-triage' \
    --add-reviewer 'alice,bob' \
    --add-assignee '@me'

@me means your authenticated account for assignee operations. The installed 2.87.3 help also supports @copilot for assigning Copilot or requesting its review, subject to GitHub's availability rules. Team reviewers use their organisation/team form, such as myorg/platform-reviewers.

Removing a reviewer, assignee or label is a remote state change. Before using a remove option, confirm the current item shows up in the output from step 2. Remove something by accident, and you can run the matching --add-... command again, provided you still know the original value and have permission.

5. Change the base branch or milestone

Changing the base branch can alter the diff GitHub shows and may affect checks or mergeability. Treat it as a deliberate review decision:

$ gh pr edit 123 --repo OWNER/REPOSITORY --base main

To associate a milestone, pass its name:

$ gh pr edit 123 --repo OWNER/REPOSITORY --milestone 'Version 1'

In the installed CLI, --remove-milestone removes the association. The local manpage supplied with this system does not list that option, so check the installed help before relying on it:

$ gh pr edit 123 --repo OWNER/REPOSITORY --remove-milestone

There is no elevated-privilege form of these commands. If GitHub rejects the operation, check repository access, the pull request's state and your authentication rather than retrying with sudo.

6. Handle project authorisation and failures

Editing projects requires the GitHub CLI project scope. If a project operation fails with an authorisation error, refresh that scope interactively:

$ gh auth refresh -s project

This changes local authentication state and may open a browser or prompt. Do it only when you intend to grant the additional scope: it will not grant repository permission your GitHub account does not already have.

A non-zero exit status means the command did not complete cleanly, but a partial result is possible for attachments in newer CLI versions: the official manual says successfully uploaded attachments can remain even when another upload fails. Check the pull request after any failure rather than blindly rerunning the whole command. For ordinary metadata edits, verify the final state explicitly:

$ gh pr view 123 --repo OWNER/REPOSITORY \
    --json number,title,body,baseRefName,labels,assignees,reviewRequests,milestone,url

If you replaced the body with the wrong text, rerun gh pr edit with the saved body file. Changed a label, reviewer, assignee or milestone by mistake? Use its matching add or remove option to restore the previous state. If the base branch was wrong, pass the original branch to --base and review the changed diff in GitHub afterwards.

Done means