Skip to content
  • Official
  • Beginner
  • English
  • 12 steps · 2 quizzes

GitHub Pull Requests: A Hands-On Workshop for Teams

GitHub pull request tutorial for teams: branch, push, open, review, fix and merge a pull request in simulated GitHub screens, with exercises.

  • Free
  • No account needed
  • Stop any time, pick up where you left off
Workshopy.io

WorkshopyOfficial

78 lessons · used by 2 teachers

For teachers

Teaching this? Run it live with your class.

  • Students join with a code — no accounts
  • See who’s done and who’s stuck, step by step
  • It’s your copy — change anything before class

Sign in to copy it to your workspace. It’s free.

Your path

12 steps · 2 quizzes · open any step, or read it here

  1. GitHub pull requests for teams: what you'll practiseStart hereIn this GitHub pull request tutorial for teams you practise the whole flow by doing it: branch, push, open a pull request, review it, fix it and merge it.InteractiveHands-on
    Read this step

    In this GitHub pull request tutorial for teams you practise the whole flow by doing it: branch, push, open a pull request, review it, fix it and merge it. You work on one change in a team's support tool, from the ticket to main, and see each step drawn as it happens.

    Here is the whole story in seven moments. Press Play, or step through it.

    Interactive · A pull request, from branch to main — try it in the lesson

    In this lesson you'll:

    • open a pull request with a title, a description and a closing keyword, as a draft first
    • review a diff with line comments and pick Comment, Approve or Request changes
    • answer a review with new commits and see why GitHub blocks a merge
    • compare Create a merge commit, Squash and merge and Rebase and merge

    It takes about 60 minutes. Each step ends with a "Try it" and one line to remember.

    Takeaway: a pull request is a conversation about one change, and main only gets the change once the conversation is done.

  2. Branch or fork: where your change livesA pull request asks to merge one branch into another. Where that branch lives depends on who you are: On the team (you have write access): make the branch in the team's repository and push it there. This is the usual flow at work.InteractiveHands-on
    Read this step

    A pull request asks to merge one branch into another. Where that branch lives depends on who you are:

    • On the team (you have write access): make the branch in the team's repository and push it there. This is the usual flow at work.
    • Outside the project (open source, another company's repository): you can't push there, so you fork it: GitHub makes a copy under your account. You push your branch to the fork and open the pull request from the fork's branch to the original repository's main, called upstream.

    Both end in the same place: a pull request into main that people review.

    Try it: switch between the two and compare where the branch lives and what you push to.

    Interactive · A branch in the team's repository, or in your fork — try it in the lesson

    Takeaway: teammates branch in the shared repository; outsiders fork it and open the pull request across repositories.

  3. Small commits on a branch, then pushTicket #12 says the CSV export of the support tool times out on big queues. You have already changed src/export/csv.js.InteractiveHands-on
    Read this step

    Ticket #12 says the CSV export of the support tool times out on big queues. You have already changed src/export/csv.js. Before anyone can review it, the change needs its own branch on GitHub:

    1. git switch -c fix/export-timeout makes the branch and moves you onto it.
    2. git add src/export/csv.js stages the file.
    3. git commit -m "Stream CSV export in batches" records it, with a message that says what it does.
    4. git push -u origin fix/export-timeout sends the branch to GitHub; -u remembers it as the branch's upstream, so later a plain git push is enough.

    Keep each commit about one thing. Reviewers read commits one by one, and a commit titled "stuff" makes them read everything.

    Try it: do the four tasks in the practice terminal. git status tells you where you are at any point.

    Interactive · Branch, commit and push in a practice terminal — try it in the lesson

    With a real repository, make the branch there too, then check that you are on it.

    Check your work · Run `git switch -c fix/export-timeout` in a repository of yours, then `git branch --show-current`, and paste what it prints. — check it in the lesson

    Takeaway: a pull request starts as a pushed branch; push it with -u the first time.

  4. Open the pull request: title, description, Closes #12When the branch is on GitHub, open a pull request from it into main: on the repository's page (GitHub offers Compare & pull request for a branch you just pushed), or with the GitHub CLI: gh pr create.InteractiveHands-on
    Read this step

    When the branch is on GitHub, open a pull request from it into main: on the repository's page (GitHub offers Compare & pull request for a branch you just pushed), or with the GitHub CLI: gh pr create.

    • Base and compare: the base is where the change should go (main), compare is your branch.
    • Title: what changes, in a few words. "Fix" tells a reviewer nothing; "Stream CSV export to stop timeouts" does.
    • Description: what, why and how to test. A line with a closing keyword and the issue number, such as Closes #12, links the issue and closes it when the pull request merges. The keywords are close, closes, closed, fix, fixes, fixed, resolve, resolves and resolved, and they work only when the base is the repository's default branch.
    • Draft pull request: not ready yet, but you want eyes on it. A draft can't be merged, and code owners aren't asked to review it. Press Ready for review when it is (or gh pr ready).

    Try it: fill in the form so all three tasks are done. Change the base to release/2.4 and watch what happens to the closing keyword.

    Interactive · Open a pull request that closes its issue — try it in the lesson

    Takeaway: a good pull request explains itself before anyone opens the diff, and Closes #12 ties it to its ticket.

  5. Who reviews: reviewers and CODEOWNERSYou can ask people for a review yourself (the Reviewers box on the right of the pull request, or gh pr create --reviewer sam).InteractiveHands-on
    Read this step

    You can ask people for a review yourself (the Reviewers box on the right of the pull request, or gh pr create --reviewer sam). Teams also write a CODEOWNERS file (in .github/, the root or docs/): each line is a file pattern and the people or teams who own those files. When a pull request changes owned files, GitHub requests a review from their owners automatically.

    Two rules to know:

    • When several lines match a file, the last matching line wins.
    • Code owners aren't requested on a draft; they are when it's marked Ready for review.

    With the branch protection setting "Require review from Code Owners" (next steps), an owner's approval is needed before merging.

    Try it: tick and untick the changed files, and see who gets asked. Then turn on Draft.

    Interactive · Which owners a pull request asks for review — try it in the lesson

    Takeaway: CODEOWNERS sends each pull request to the people who know those files, and the last matching line decides.

  6. Read the diff, leave review commentsAs a reviewer you open Files changed: red lines were removed, green lines added. To check it out and run it yourself, gh pr checkout 14 fetches the branch into your clone.InteractiveHands-on
    Read this step

    As a reviewer you open Files changed: red lines were removed, green lines added. To check it out and run it yourself, gh pr checkout 14 fetches the branch into your clone.

    • Comment on the line where the problem is, and say why: "This logs every export to production logs; can we drop it?" A question or a reason helps more than an order.
    • Your comments wait as a pending review until you press Submit review and pick one of three:
      • Comment: general feedback, without approving.
      • Approve: it can merge as it is.
      • Request changes: something must change before it merges.

    Try it: find the two lines that need a change, comment on each, then submit the review so it blocks the merge.

    Interactive · Review a diff with line comments — try it in the lesson

    Takeaway: comment on the line, give the reason, and pick the review type that says what must happen next.

  7. Answer the review with new commitsThe author doesn't open a new pull request. They fix the code on the same branch and push; every new commit appears in the pull request at once, and a comment on a line that changed is marked Outdated.InteractiveHands-on
    Read this step

    The author doesn't open a new pull request. They fix the code on the same branch and push; every new commit appears in the pull request at once, and a comment on a line that changed is marked Outdated.

    1. Fix the code, then git add, git commit -m "Remove debug log" and git push (the upstream is set, so no -u).
    2. Reply in each thread with what you did, then Resolve conversation.
    3. Press Re-request review (the circular arrows beside the reviewer's name) so the reviewer knows it's ready.

    Avoid rewriting commits a reviewer has already read, with an amend or a force push, while the review is going on: they lose track of what changed since their last look.

    Try it: work through both threads, then re-request the review.

    Interactive · Push fixes, reply, resolve, re-request — try it in the lesson

    Takeaway: answer a review with new commits on the same branch, a reply in each thread, and a re-request.

  8. Check: opening and reviewing a pull requestFour questions on the steps so far.Quiz · 4 questions
    Read the questions

    Four questions on the steps so far.

    Question 1. You are not a member of an open-source project and want to propose a fix. What do you do first?

    • Push a branch to the project's repository
    • Fork the repository and push your branch to the fork
    • Ask for the main branch to be unprotected
    • Open a pull request with no branch

    Question 2. Which description line closes issue 12 when the pull request merges into main?

    • Related to #12
    • Resolves #12
    • Issue 12 is done
    • See #12

    Question 3. A reviewer found a bug that must be fixed before merging. Which review type fits?

    • Comment
    • Approve
    • Request changes

    Question 4. After a review, how does the author bring the fixes into the pull request?

    • Close it and open a new pull request
    • Commit on the same branch and push
    • Edit the diff on the Files changed tab
    • Merge main into the reviewer's branch
  9. Checks and branch protection: why merging is blockedTwo things guard main on most teams: Status checks: GitHub Actions (or another CI) runs the tests and the linter on every push to the pull request. Their results show at the bottom of the pull request as passing, failing or still running.InteractiveHands-on
    Read this step

    Two things guard main on most teams:

    • Status checks: GitHub Actions (or another CI) runs the tests and the linter on every push to the pull request. Their results show at the bottom of the pull request as passing, failing or still running.
    • A branch protection rule (or a ruleset) on main, set by a maintainer, decides what merging needs, for example: Require a pull request before merging with a number of Required approvals, Require status checks to pass before merging, Require conversation resolution before merging.

    When a rule isn't met, the merge box says Merging is blocked and lists why. A request for changes counts too: that reviewer must approve a newer version, or the review must be dismissed.

    Try it: make the merge button turn on. Then turn off a rule and see what it no longer guards.

    Interactive · What the merge box needs before main takes a change — try it in the lesson

    Takeaway: checks prove it works, approvals prove someone read it, and branch protection makes both required.

  10. Merge commit, squash or rebase: what lands on mainThe merge button offers up to three methods (the repository settings decide which): Create a merge commit: all the branch's commits go into main, joined by a merge commit. The full story stays, review fixes included.InteractiveHands-on
    Read this step

    The merge button offers up to three methods (the repository settings decide which):

    • Create a merge commit: all the branch's commits go into main, joined by a merge commit. The full story stays, review fixes included.
    • Squash and merge: all the commits become one commit on main, named after the pull request. main reads one commit per change.
    • Rebase and merge: each commit is replayed on top of main, with no merge commit. A straight line, but every commit gets a new ID.

    The pull request below has three commits: the change and two review fixes. main got a commit (M2) since the branch started.

    Try it: pick each method and count the new commits on main.

    Interactive · Three ways to merge the same pull request — try it in the lesson

    Takeaway: merge commit keeps everything, squash keeps one commit per pull request, rebase keeps a straight line with new IDs.

Comments

You’ll sign in with Google before it’s posted.Comments are public — don’t name your students.
0 / 1,500

No comments yet. Be the first to say how it went.

Using it

Workshopy shares this lesson under CC BY 4.0. Anyone may use and change it, with credit to you. Anyone can learn it here, free. A copy in your workspace is yours to change and run live; your students never need an account.

Versions

  1. 1

    Version 1Current

    · First published

Copies are made from the current version. A copy you already have doesn’t change.

More from Workshopy

All 78 lessons
All 13 Programming lessons