Pull Requests

This content was generated with the assistance of AI and should be verified against the official documentation before being relied on in production; see the section bibliography for the reference material consulted while preparing these pages.

A pull request is a proposal to merge one branch — the compare or head branch — into another — the base branch — together with the discussion, review comments and automated checks that happen before that merge. This page walks through opening, reviewing and merging a pull request on github.com, with the GitHub CLI, in IntelliJ IDEA and in VS Code. It reflects Git 2.55.x, GitHub CLI 2.101.x, IntelliJ IDEA 2026.2, the current stable VS Code with the GitHub Pull Requests and Issues extension (GitHub.vscode-pull-request-github), and github.com as of September 2026, with a default branch named main.

Concept

A pull request does not move any commits by itself: the commits already exist on the compare branch, pushed to the remote (see Fetch, Pull and Push). What a pull request adds is a page that shows the diff between the two branches, lets people comment on individual lines, tracks required status checks, and finally performs the merge into the base branch (see Merging, Rebasing and Conflicts for what that merge does to history). It is a GitHub feature layered on top of plain Git, not a Git concept — Git itself has no notion of a pull request.

GitHub flow, end to end

The typical lifecycle of a change on GitHub — GitHub flow — has six steps:

  1. Create a branch off main with a descriptive name (see Branches).

  2. Commit changes on that branch and push it to the remote.

  3. Open a pull request asking collaborators to review the change.

  4. Address review comments with more commits, pushed to the same branch.

  5. Merge the pull request once it is approved and its checks pass.

  6. Delete the branch; the pull request and its commit history remain.

flowchart LR a["1. Create a branch"] --> b["2. Commit and push"] b --> c["3. Open a pull request"] c --> d["4. Review and revise"] d -->|more commits| b d -->|approved| e["5. Merge"] e --> f["6. Delete the branch"]

Derived from GitHub flow.

Draft pull requests

A pull request can be opened as a draft. A draft signals that the work is not ready for a formal review: it cannot be merged, and it does not request reviews from code owners the way a ready pull request does. Marking a draft Ready for review converts it to a normal pull request and triggers those review requests. Draft pull requests are useful for sharing work in progress, getting early feedback, or letting CI run before asking anyone to look at the diff. Derived from About pull requests.

Pull request templates

A repository can define a pull request description template at .github/pull_request_template.md (or several templates under .github/PULL_REQUEST_TEMPLATE/). When a template exists, GitHub — and the IntelliJ IDEA and VS Code integrations covered below — pre-fill the description field with its content, so contributors fill in a checklist instead of starting from a blank box. This is analogous to an issue template, just for pull requests.

Linking issues

Writing a recognised keyword followed by an issue reference in the pull request description creates a link between the two, and merging the pull request into the repository’s default branch automatically closes the linked issue. Recognised keywords include close, closes, closed, fix, fixes, fixed, resolve, resolves and resolved:

Closes #123
Fixes owner/other-repo#456

Several issues can be linked in one description by repeating the keyword for each one. If the keyword is later removed from the description, the link (and the automatic close) is undone. Derived from Linking a pull request to an issue.

Pull requests from forks

When a contributor does not have push access to a repository, they fork it, push their branch to the fork, and open the pull request against the upstream repository by clicking compare across forks and picking the fork and branch as the compare side. The author of a fork-based pull request can tick Allow edits from maintainers so that maintainers can push small fixes directly to the contribution instead of asking for another round trip. Derived from Creating a pull request from a fork.

Create a PR on github.com

  1. Push the branch to the remote (see Fetch, Pull and Push). Github.com then shows a yellow Compare & pull request banner on the repository’s main page for that branch; alternatively, open the Pull requests tab and click New pull request.

  2. Click Compare & pull request, or on the New pull request page pick the base branch (the drop-down on the left, where changes will be merged) and the compare branch (the drop-down on the right, the branch with the changes).

  3. Enter a title and a description. If .github/pull_request_template.md exists, the description starts pre-filled with it.

  4. In the sidebar, optionally pick reviewers, assignees and labels.

  5. Click Create pull request for a normal pull request, or open the split-button drop-down next to it, choose Create draft pull request, and confirm with Draft Pull Request for a draft.

Derived from Creating a pull request.

With the GitHub CLI

gh pr create opens a pull request from the current branch. Run without flags, it prompts interactively for a title and a body (with the option to open the description in your editor), then asks whether to submit, submit as a draft, continue in the browser or add metadata; the base branch is not prompted for and defaults to the repository’s default branch:

gh pr create

Flags skip the prompts and are handy in scripts:

gh pr create --base main --head feature/142 \
  --title "Add pagination to the search endpoint" \
  --body "Closes #142" \
  --reviewer octocat --reviewer another-teammate

--base names the branch to merge into (defaults to the repository’s default branch); --head names the branch with the changes (defaults to the current branch); --draft opens it as a draft; --web skips the prompts and opens the browser at the prefilled New pull request page instead of creating anything from the terminal. Derived from gh pr create.

Everyday follow-up commands:

gh pr list                    # open pull requests in the current repository
gh pr view 142                # description, checks and review status of PR #142
gh pr view 142 --web          # same, opened in the browser
gh pr checkout 142            # fetch PR #142's branch and switch to it locally
gh pr review 142 --approve
gh pr review 142 --request-changes --body "Please add a test for the empty-page case"
gh pr review 142 --comment --body "Nice cleanup"
gh pr merge 142 --squash --delete-branch

gh pr checkout is the fastest way to pull someone else’s pull request — including one from a fork — onto your machine for a local look; see Checkout, Switch and Restore for what happens to the working tree when a branch is checked out. gh pr review submits an approval, a change request or a plain comment without opening the browser. gh pr merge accepts --merge, --squash or --rebase for the three merge methods described below, and --delete-branch removes the local and remote branch once the merge succeeds. Derived from gh pr list, gh pr view, gh pr checkout, gh pr review and gh pr merge.

In IntelliJ IDEA

Creating a pull request

  1. With the branch pushed, choose Git > GitHub > Create Pull Request. The same action is available from the + button in the Pull Requests tool window, and IntelliJ IDEA also offers it in a notification right after a push.

  2. Pick the base repository and base branch on the left side of the dialog, and the head branch (your branch) on the right side.

  3. Review the diff shown below the branch pickers.

  4. Fill in the title and description — pre-filled from .github/pull_request_template.md when the repository has one — and add reviewers, assignees and labels.

  5. Click Create Pull Request, or Create Draft Pull Request to open it as a draft.

Reviewing and merging an incoming pull request

  1. Open Git > GitHub > View Pull Requests to list the repository’s pull requests, filterable by state, author, label and review status.

  2. Double-click a pull request and choose Checkout to fetch its branch and enter review mode, which marks changed lines in the editor gutter.

  3. Hover a changed line’s gutter and click the add icon to comment: Add Single Comment posts immediately, Start Review batches several comments as pending.

  4. Click Submit and choose Approve, Request changes or Comment to finish the review.

  5. To merge, use the Merge button in the Pull Requests tool window, or its drop-down for Squash and Merge or Rebase and Merge — the same three methods described below.

Derived from JetBrains' "Create and merge GitHub pull requests" and "Review incoming GitHub pull requests" pages.

In VS Code

  1. Install the GitHub Pull Requests and Issues extension (GitHub.vscode-pull-request-github) from the Marketplace, then sign in with GitHub from the extension’s Activity Bar icon.

  2. With your branch committed and pushed, run GitHub Pull Requests: Create Pull Request from the Command Palette, or click Create Pull Request in the GitHub Pull Requests view.

  3. Pick the target (base) branch when prompted.

  4. Fill in the title and description — auto-filled from .github/pull_request_template.md when one exists.

  5. Click Create, or Create as Draft for a draft; if the branch is not published yet, choose the remote to publish it to first.

Once open, the extension switches to review mode: the diff for the pull request’s branch is shown in the editor, comments appear inline in the gutter with @-mentions and #-issue references, and you can leave your own comments the same way. From the GitHub Pull Requests view you can check out any listed pull request locally with one click — including someone else’s — to run and test it, submit a review (comment, approve, request changes) from the pull request’s Description page, and merge it from the same view once it is ready. Derived from VS Code’s "Working with GitHub" page and the extension’s Visual Studio Marketplace page.

Reviewing and merging on github.com

  1. Open the pull request and click the Files changed tab to see the diff (unified or split, whitespace changes optionally hidden).

  2. Hover a line to comment on it, or click a line number and shift-click another to comment on a range; use the suggestion button to propose an exact replacement the author can accept with one click.

  3. Click Review changes, write a summary, choose Comment, Approve or Request changes, and click Submit review. Comments stay pending and visible only to you until submitted.

  4. If the repository requires status checks or reviews, the merge button stays disabled until they pass — checks show as a list near the bottom of the Conversation tab.

  5. Once mergeable, scroll to the bottom of the Conversation tab, pick a merge method, confirm the commit message, and click Confirm merge, Confirm squash and merge or Confirm rebase and merge.

  6. Optionally click Delete branch on the confirmation banner, then update your own clone with git switch main && git pull.

Derived from Reviewing proposed changes in a pull request and Merging a pull request.

When the pull request was opened by a Cloud & Background Agent or otherwise contains AI-generated changes, see Reviewing AI-Generated Code for what to check before approving it.

The three merge methods

Merge commit keeps every commit from the pull request branch and adds a merge commit on top, so the base branch’s history shows exactly what happened, including intermediate work:

gitGraph commit id: "base-1" branch feature commit id: "wip-1" commit id: "wip-2" checkout main commit id: "base-2" merge feature id: "Merge PR #142"

Squash and merge collapses every commit on the pull request into a single new commit on the base branch, so work-in-progress or fixup commits disappear from `main’s history:

gitGraph commit id: "base-1" branch feature commit id: "wip-1" commit id: "wip-2" checkout main commit id: "base-2" commit id: "Squashed PR #142"

Rebase and merge replays the pull request’s commits one by one onto the tip of the base branch, with new commit identifiers, keeping a linear history and no merge commit:

gitGraph commit id: "base-1" branch feature commit id: "wip-1" commit id: "wip-2" checkout main commit id: "base-2" cherry-pick id: "wip-1" tag: "rebased" cherry-pick id: "wip-2" tag: "rebased"

Choose a merge commit when the team wants full traceability of every intermediate commit, squash and merge when a pull request represents one logical change and its commit-by-commit history is not worth keeping, and rebase and merge when the team wants a linear history and the commits are already clean. Whichever method is used, the merge itself follows the same rules as a local merge or rebase; see Merging, Rebasing and Conflicts for conflict resolution. A repository can also enable auto-merge, which merges a pull request automatically once its requirements are satisfied, and, for repositories under heavy contention, a merge queue that serialises merges and re-tests each one against the latest base branch — both are configured per repository and out of scope for this walkthrough. Derived from About pull request merges.

Common mistakes / tips

  • Opening a pull request against the wrong base branch is easy to fix without recreating it: use the base-branch drop-down at the top of the pull request page (or the Edit button) to retarget it.

  • A description without a linking keyword (Closes #123) leaves the issue open after merge; add the keyword before merging, not after — editing it afterwards does not retroactively close anything.

  • Squash and merge rewrites every commit into one, so anyone who already has the feature branch checked out locally will see it diverge from main after the merge; delete the local branch and re-branch from the updated main rather than trying to fast-forward it.

  • A draft pull request cannot be merged even if all its checks pass — mark it Ready for review first.

  • .github/pull_request_template.md only pre-fills the description on creation; editing it later does not update pull requests that are already open.

References