Pull Requests Explained: How to Create and Review Them

A pull request (PR) is a proposal to merge changes from one branch into another. It is also the shared place where contributors discuss the change, review its code, and check whether repository requirements are satisfied. Creating a PR does not merge it; merging happens later, after the required review and checks.

This guide covers the usual GitHub workflow, with both the website and GitHub CLI, plus how to review a PR, respond to feedback, handle drafts, and diagnose common blockers. GitHub’s requirements and interface can vary by repository settings and may change, so use the PR’s status area and repository guidance as the source of truth for a particular change.

What happens in a pull request?

A PR compares a head branch (the branch containing your work) with a base branch (the branch intended to receive it). Reviewers can discuss the proposal, inspect its diff and commits, and check automated status checks before it is merged.

The common sequence is:

Create a branch, or fork the repository if you do not have write access.
Make a focused change and commit it.
Open a PR from your work branch to the intended base branch.
Reviewers comment or submit a review; the author may update the branch.
Merge when the repository’s configured requirements are met.

Smaller, focused PRs are generally easier to understand and review. GitHub Docs also notes that smaller PRs are faster to review and easier to merge. A PR can include code, documentation, configuration, or other changes tracked in the repository.

Before you create a pull request

Choose the right repository and base branch. Check the project’s contribution guide if it specifies a target branch or process.
Use a branch if you can push to the repository. If you lack write access, fork the repository and push your branch to your fork.
Keep the change focused. Separate unrelated fixes when practical so reviewers can assess each proposal clearly.
Prepare a useful summary. State what changed and why. Mention relevant context, testing or checks you ran, and any known limitations without claiming checks you did not perform.

How do I create a pull request?

Option 1: Create one on GitHub.com

Make your change in a branch. You can edit files in the GitHub interface or work locally, commit, and push the branch. If you cannot push to the upstream repository, create a fork and work there.
Open the repository and select Pull requests, then New pull request.
Choose the base branch that should receive the changes and the compare branch that contains your work. If working from a fork, select the correct repository and branch on each side.
Inspect the changed files shown in the comparison. Confirm that the diff contains the changes you intend to propose and does not target the wrong base.
Enter a concise title and a description explaining what changed and why. Include relevant context and what you checked.
Create the PR as ready for review if you want formal feedback now, or choose Create draft pull request if the work is still in progress.
Request an appropriate reviewer if you have the required access. GitHub documents that requesting a review requires write access; people or teams with read access can be requested. Reviewer availability can vary with repository visibility and plan.

Option 2: Create one with GitHub CLI

The following is a runnable pattern for a repository where you can push a branch. Replace the branch names and PR text with your own. The GitHub CLI must be installed and authenticated, and the repository should be the current directory.

git switch -c fix/clear-error-message
# Make and save your changes
git add path/to/changed-file
git commit -m "Clarify error message"
git push -u origin fix/clear-error-message

gh pr create \
  --base main \
  --head fix/clear-error-message \
  --title "Clarify the error message" \
  --body "## What changed\n- Explain the error more clearly\n\n## Why\n- Help users identify the next step\n\n## Checks\n- Describe the checks you actually ran"

To open a draft using the CLI, add --draft to gh pr create. If the repository uses another base branch, replace main. In a fork workflow, ensure the head branch is the branch in your fork and that the base points to the upstream repository and intended branch; the CLI can use a OWNER:BRANCH head value when needed. Use gh pr create --help for the installed CLI’s available flags.

What to put in the PR description

There is no universal required template, but a useful description answers:

What changed?
Why is the change needed?
How can a reviewer verify it?
Are there tradeoffs, follow-up work, or known limitations?

Link related context when relevant and follow the repository’s contribution instructions. Avoid vague titles such as “Fix” or descriptions that merely repeat the title.

What is a draft pull request?

A draft PR shares work in progress without signaling that it is ready for formal review. Use one when you want early discussion, need to show progress, or still expect substantial changes. A draft cannot be merged. Code owners are not automatically requested while it remains a draft; marking it ready for review requests review from code owners.

State	Use it when	What it signals
Draft	The proposal is incomplete or you want early discussion	Work is in progress; it cannot be merged yet
Ready for review	You want reviewers to assess the current proposal	Formal review can begin; configured review requests apply

When ready, use the PR’s Ready for review control. Before doing so, check that the description and diff are reviewable and that you have addressed any known incomplete work.

How do I review a pull request?

Understand the purpose first. Read the PR title, description, and discussion. Check the target branch and the change’s stated scope.
Inspect the diff and, when helpful, the commits. Review files in context. Consider whether the change does what the description claims and whether it creates obvious regressions, missed cases, or maintenance problems.
Use focused comments. Leave a general comment for broad feedback or a line comment for a specific issue. If you know the exact edit, a suggested change can make it easier for the author to apply.
Submit your review. In GitHub’s review interface, you can gather pending comments and submit them together with a summary and a decision.
Check status checks and outstanding feedback. An approval by itself does not guarantee that the PR can merge.

Comment, approve, or request changes?

Review decision	Meaning	Good fit
Comment	Shares feedback without an approval decision	You have observations or questions but are not signaling approval or requesting changes
Approve	Signals that you consider the changes ready	You have reviewed the proposal and support it
Request changes	Flags work you want addressed	You found a concern that should be resolved or discussed before the change proceeds

A request for changes does not automatically block merging in every repository. Whether it blocks a merge depends on branch protection or ruleset configuration and the reviewer’s permissions. Explain the concern clearly and state what would resolve it.

How should an author respond to review feedback?

Read each comment for the issue it is trying to address. Ask for clarification if the requested outcome is unclear.
Apply an inline suggestion when it fits, or make a broader change in a new commit. Keep the PR’s branch updated so the diff reflects the current proposal.
Reply when context or a decision needs explanation. Resolve conversations once the point is addressed, following the project’s review norms.
When the updates are substantial, request another review if appropriate. Check that required checks have completed and that no review or conversation remains outstanding.

Commits pushed to the same branch update the existing PR. You normally do not need to open a second PR for follow-up changes to that proposal.

How do I merge a pull request?

First check the PR’s status area and repository instructions. Required approvals, status checks, conversation resolution, permissions, and other merge rules depend on the repository’s configuration. GitHub’s quickstart workflow requires its configured reviews and checks to be satisfied before merging, but requirements differ between repositories.

Confirm the PR targets the intended base branch and that its latest diff is the one you mean to merge.
Review required approvals, requested changes, unresolved conversations, and automated checks shown by GitHub.
Address any failing or pending requirement, or ask a repository maintainer what applies if the status is unclear.
When GitHub enables the merge control and repository policy permits it, choose an available merge method and complete the merge. The available methods depend on repository settings.

Do not assume that an approval is sufficient, that every review decision has the same blocking effect, or that every repository enables the same merge methods. If you do not have merge permission, ask a maintainer to complete the process.

Direct branch or fork?

Workflow	Choose it when	Basic shape
Branch in the repository	You have permission to push a branch to the project repository	Branch → push to repository → PR to its base branch
Fork	You do not have write access to the upstream repository	Fork → branch in your fork → PR from fork to upstream

In either case, verify the PR’s head and base repositories and branches before creating it. A correct diff sent to the wrong base is still the wrong proposal.

Common problems and fixes

Problem	Likely cause	What to do
The compare page shows no changes	The head branch has no commits ahead of the selected base, or the wrong branches were selected	Check the branch names, repository, and commit history; push your commits if they exist only locally.
The PR contains unrelated files or commits	The branch was based on the wrong branch or accumulated unrelated work	Inspect the base and compare selections and clean up the branch so the diff matches the proposal.
You cannot push or request a review	You may lack write access or the permission needed for that action	Use a fork when you cannot write to the repository; ask a maintainer about review access or repository policy.
The PR cannot be merged	It may still be a draft, required checks or approvals may be missing, a conflict may need resolution, or your account may lack permission	Read the status area, satisfy the listed requirements, mark a draft ready when appropriate, and contact a maintainer if access or policy is the blocker.
A requested change appears not to block merging	Request-change blocking behavior depends on repository rules and reviewer permissions	Check branch protection or ruleset guidance and ask a maintainer; do not assume every request blocks every merge.
The CLI cannot find the repository or PR target	The current directory may not be a GitHub repository, authentication may be missing, or the base/head is wrong	Run the command from the repository, authenticate the CLI, and specify the intended base and head. Check `gh pr create --help` for supported options.
A draft is not receiving code owner review	Code owners are not automatically requested while the PR is a draft	Mark it ready for review when the work is ready for formal review.

Good PR habits

Make the title specific and the description useful to someone who did not write the change.
Keep the proposed change focused and inspect the final diff before asking for review.
Use draft status to share incomplete work honestly.
Keep comments specific, respectful, and actionable; distinguish a question from a blocking concern.
Use the status area and project guidance to understand merge requirements instead of assuming every repository works the same way.

Or skip the browser setup

If a pull request workflow also involves capturing a page for documentation or review, ScreenshotNeo can return a screenshot or PDF from one API request. See the ScreenshotNeo API documentation.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://github.com -o shot.webp

import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://github.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://github.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

ScreenshotNeo removes cookie banners, popups, and chat widgets before the shot. Bot checks, blank pages, and failed loads are never billed. Its MCP server lets AI agents take screenshots. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000. Sign up for free and get 1,000 screenshots a month with no card.

FAQ

Does opening a pull request merge my changes?

No. It proposes a merge and starts the discussion and review process. The merge is a later action.

Can I update a pull request after creating it?

Yes. Push additional commits to its head branch and the existing PR updates.

Can I create a pull request if I cannot write to the repository?

Usually you can contribute through a fork: push your branch to your fork and propose it as a change to the upstream repository.

Does every pull request need an approval?

That depends on the repository’s rules. Check its PR status and contribution guidance for the requirements that apply.