GitHub Pull Requests Explained: Create, Review and Merge

A pull request (PR) is a request to merge your branch into another branch, usually main. It is a page on GitHub showing what changed, where teammates can comment before the code is accepted. In most companies, code reaches main only through pull requests.

Pull requests are a GitHub feature, not a Git one. GitLab calls them merge requests.

The workflow#

1. Create a branch    2. Commit    3. Push
4. Open a PR          5. Review    6. Merge     7. Delete the branch

Step 1: Branch, commit, push#

Always start from an up-to-date main:

git switch -q main
git pull -q
git switch -c add-contact-page
echo "Contact us" > contact.html
git add .
git commit -q -m "Add contact page"
git push -u origin add-contact-page

Switched to a new branch 'add-contact-page'
To https://github.com/your-name/shop.git
 * [new branch]      add-contact-page -> add-contact-page
branch 'add-contact-page' set up to track 'origin/add-contact-page'.

Step 2: Open the pull request#

Go to your repository on GitHub. A Compare & pull request banner appears for branches you have just pushed. Click it, or open the Pull requests tab and click New pull request.

• Check that base is main and compare is your branch.
• Write a clear title, such as "Add contact page".
• In the description, explain what changed, why, and how you tested it.
• Choose reviewers on the right.
• Click Create pull request.

A useful description looks like this:

## What
Adds a contact page linked from the footer.

## Why
Customers had no way to reach us. Closes #12.

## How I tested
Opened the page on desktop and phone, and checked the footer link.

Writing Closes #12 closes issue 12 automatically when the PR is merged.

To do the same from a terminal with the GitHub CLI:

gh pr create --title "Add contact page" --body "Adds a contact page."

Step 3: Code review#

Reviewers read the Files changed tab and can comment on any line. They finish with one of three responses: Comment, Approve, or Request changes.

To make changes, keep working on the same branch. New commits appear in the PR automatically:

echo "Phone: 000-000-0000" >> contact.html
git commit -q -am "Add phone number after review"
git push

To https://github.com/your-name/shop.git
   b65910e..6aefa20  add-contact-page -> add-contact-page

Being a good reviewer#

• Check that the code works and solves the problem, not only its style.
• Explain why, and suggest an alternative: "This query runs once per user; could it fetch them all at once?"
• Comment on the code, never the person.
• Approve when it is good enough. It does not need to be how you would have written it.

Being a good author#

• Keep pull requests small. A short PR gets a much better review than one with 2,000 changed lines.
• Read your own diff first.
• Reply to every comment, and do not take feedback personally.

Step 4: Merge#

When the PR is approved and checks have passed, GitHub offers three buttons:

Step 5: Clean up#

Delete the branch with the button on GitHub, or use git push origin --delete add-contact-page. Then update your computer. Here we run the same merge locally, in place of pressing the button on GitHub:

git switch main
git pull
git branch -d add-contact-page
git fetch --prune

Already on 'main'
Your branch is behind 'origin/main' by 3 commits, and can be fast-forwarded.
  (use "git pull" to update your local branch)
Updating 4e04c7b..18af009
Fast-forward
 contact.html | 2 ++
 1 file changed, 2 insertions(+)
 create mode 100644 contact.html
Deleted branch add-contact-page (was 6aefa20).

Keeping your branch up to date#

If main moves while your PR is open, bring those changes into your branch:

git switch add-contact-page
git fetch origin
git merge origin/main
git push

GitHub tells you if there are conflicts. Fix them locally in the usual way and push.

Protecting main#

Under Settings, then Branches (or Rules), teams can protect main so that nobody can push to it directly, and every change needs an approved PR and passing checks.

Common mistakes#

Key takeaway#

Next: Forks and Contributing to Open Source.