Close a GitHub Pull Request Safely with gh pr close

You will close one GitHub pull request from a terminal, optionally leave a closing comment, and verify that GitHub now reports it as closed. The examples use GitHub CLI 2.87.3, installed here from the gh package. Allow about five minutes if you already know the repository and pull request number.

Before you start

You need:

• GitHub CLI installed and authenticated with an account allowed to close the pull request.
• The repository name, in OWNER/REPO form, if you are not running inside its local checkout.
• The pull request number, URL, or source branch name.

Closing a pull request changes shared GitHub state. It does not merge the work, and it is not a substitute for deleting a branch. Read the target twice before you run the command. No elevated privileges are normally needed: this is a GitHub API operation, not a local system administration task.

1. Confirm the target

Use gh pr view to check the title, repository and current state. Replace every uppercase placeholder before pressing Enter:

gh pr view PR_NUMBER --repo OWNER/REPO --json number,title,state,headRepository,headRefName

A useful response looks like this:

{
  "headRefName": "feature/example",
  "headRepository": {"name": "REPO"},
  "number": 123,
  "state": "OPEN",
  "title": "Describe the change"
}

If you are already in the repository, --repo OWNER/REPO can be omitted. The close command accepts a number, URL or branch, but it still requires one of those arguments. It does not silently infer the pull request from your current branch.

2. Close it without deleting anything

The smallest command is:

gh pr close 123 --repo OWNER/REPO

You can use the complete URL instead, which is helpful when several repositories have a pull request numbered 123:

gh pr close https://github.com/OWNER/REPO/pull/123

On success, the command exits with status 0 and normally prints a confirmation identifying the pull request. Check the state explicitly afterwards:

gh pr view 123 --repo OWNER/REPO --json state --jq '.state'

CLOSED

If it fails, do not repeat the close command blindly. A status of 4 means authentication is required; status 1 means an error; status 2 means the command was cancelled. Check the repository, credentials and permissions, then inspect the original error.

3. Leave a closing comment when context matters

Use --comment when reviewers need a short record of why the pull request is being closed:

gh pr close 123 \
  --repo OWNER/REPO \
  --comment "Closing this in favour of #456; the replacement keeps the reviewed changes."

Quote the comment so shell characters and spaces stay inside one argument. Prefer a comment that explains the next action or points to a replacement. Do not put credentials, tokens, private incident details or unreviewed sensitive data into a public pull request comment.

Verify both pieces of state:

gh pr view 123 --repo OWNER/REPO --json state,comments --jq '{state: .state, latest: .comments[-1].body}'

The comment is visible to anyone who can view the pull request. Treat it as durable project history, not as a private note.

4. Decide separately about branch deletion

--delete-branch asks gh to delete both the local and remote branch after closing the pull request:

gh pr close 123 --repo OWNER/REPO --delete-branch

This is the destructive option. It can remove unmerged work and affect other clones or people still using the branch. Do not add it just to tidy the pull request list. First check the pull request diff, confirm that the branch is disposable, and make a tag or backup branch if the commits might be needed later.

If you only want the pull request closed, leave --delete-branch out. A remote branch can be removed later through the normal GitHub or Git workflow, after its owner agrees.

Undo a mistaken close

A closed, unmerged pull request can be reopened with the companion command:

gh pr reopen 123 --repo OWNER/REPO

Confirm the recovery:

gh pr view 123 --repo OWNER/REPO --json state --jq '.state'

OPEN

Reopening does not restore a branch deleted with --delete-branch. If that happened, recover the branch from another clone, a tag, or a commit reference before reopening, then verify the pull request's head branch and diff. A merged pull request is a different state and is not made open again by this workflow.

Common traps

• Wrong repository: a number is only unique within a repository. Use the full URL or an explicit --repo value when context is uncertain.
• Wrong branch assumption: the required target argument is not automatically taken from the current branch. Supply the branch name explicitly if that is how you identify the pull request.
• Unexpected authentication: run gh auth status and confirm the selected host and account. Authentication does not guarantee permission to close every repository's pull request.
• Comment lost in a shell: keep the whole comment inside quotes. For longer text, prepare it in a reviewed file and use the command supported by the relevant comment workflow rather than pasting secrets into shell history.
• Branch vanished: closing alone does not delete branches. If a branch is missing, look for another clone or a commit reference before attempting recovery.