# 15.3 GitHub and the pull request (/building-ai-workers/code-review/github-and-the-pull-request)

---
type: Document
title: "15.3 GitHub and the pull request"
description: "A remote copy of the repository, pushing and pulling, forks, and the parts of a pull request, opened and read through the agent."
status: stable
order: 315.03
ksor:
  owner: team:panaversity
  audience: [ public ]
  approval:
    by: process:panaversity
    at: 2026-11-02T18:33:52Z
chapter: "15"
part: III
expert_status: builder-only
concepts: [ "15.3" ]
last_verified: 2026-10-31
sources:
  - id: pro-git-remote-branches
    title: "Pro Git, Remote Branches (accessed 2026-10-31)"
    resource: https://git-scm.com/book/en/v2/Git-Branching-Remote-Branches
  - id: github-protected-branches
    title: "About protected branches (GitHub, accessed 2026-10-31)"
    resource: https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches
  - id: github-rulesets
    title: "About rulesets (GitHub, accessed 2026-10-31)"
    resource: https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets
generated:
  at: 2026-11-02T18:33:52Z
  by: esl-rewrite/1.2.0+ksor.1
trust_tier: unverified
build_id: sha256:e1fbcb7d9a8f8b9b7cb96875022325c02c9ba4be94cef13b301cbd39a9edad85
dirty: true
ksor_version: 0.0.60
---

**In everyday life.** A team keeps the signed copy of a contract in a shared office, not on anyone's laptop. To change it, you bring the office a draft with your changes marked. Colleagues read it and comment, and someone with the authority signs. Only then does the shared copy change.

**What you will learn.** How a shared copy of your repository works, and what the parts of pull requests are for.

**Why it matters.** The host, the service that keeps the shared copy, is where a team, its checks and its reviewers all see the same change.

### What is a hosting service for?

A **hosting service** keeps a shared copy of the repository on a server, so a team, its automated checks and its reviewers all see the same thing. Git itself works on your computer. GitHub is the most common hosting service, and this chapter uses it. GitLab and others work the same way.

- A **remote** is a copy of the repository somewhere else, usually named `origin`.
- **Pushing** sends your commits to the remote. **Pulling** brings the remote's new commits to you.
- **Cloning** makes a full copy of a remote repository on your computer.
- A **fork** is someone else's copy of a repository on the host. A change from a fork comes from outside your team, so it is treated with more care ([15.9](approval-scaled-by-risk.md)).

### Why are there three `main`s?

Because your computer and GitHub each keep a `main`, and your computer also keeps a record of GitHub's. Telling them apart prevents most beginner mistakes:

| Name | Where it lives | What it is |
| --- | --- | --- |
| `main` | Your computer | Your branch. It moves when you commit, merge or pull |
| `origin/main` | Your computer | Git's record of the host's `main` as it was the last time you fetched. You never commit to it |
| `main` on the host | GitHub | The shared branch. It moves when pull requests merge |

When pull requests merge on the host, only the host's `main` moves. `git fetch` downloads the new commits and updates `origin/main`, without touching your branches. `git status` then tells you whether your `main` is behind. `git pull` is a fetch followed by a merge of `origin/main` into your `main`. Run `git switch main` and `git pull` before you start new work or merge `main` into a branch.

Pushing with `git push -u origin main` the first time sets your `main`'s **upstream**: the remote branch a plain `git pull` and `git push` use. `git pull --ff-only` is the careful form. It moves your `main` forward only if GitHub's `main` already has all your commits. If each has commits the other lacks, they have diverged, and it stops, so a surprise never turns into a merge you did not mean to make.[^pro-git-remote-branches]

![Your computer holds main, your local branch, and origin/main, your local record of GitHub's main. GitHub holds main, the shared branch, which merged pull requests update. Step 1, git fetch origin, copies GitHub's main into origin/main. Step 2, git merge --ff-only origin/main, moves your main forward. A note says fetch does not update your local main, and --ff-only stops if main has diverged.](img/two-copies-of-main.png)

*Figure 15.6. Three `main`s in two places. Merged pull requests move GitHub's `main`. Fetch updates `origin/main`. A fast-forward, a simple move ahead, then moves yours, which `git pull --ff-only` does in one step.*

### What is a pull request?

You push a branch, then open a **pull request**: a request to merge that branch into `main`, with a page where the change is described, checked, discussed and decided. GitLab calls it a merge request. Its parts:

| Part | What you do there |
| --- | --- |
| Title and description | Say what the change is for, how it was tested, its risk and how to undo it. A template can ask for these ([15.8](checks-that-block.md)) |
| Files changed | Read the diff, and comment on a single line |
| Commits | See the steps. A new commit after an approval can cancel the approval, if the repository dismisses stale approvals ([15.9](approval-scaled-by-risk.md)) |
| Conversation | Reviewers' comments and answers, each thread closed when it is settled |
| Checks | The automated runs, each passing, failing or only advising |
| Merge | Allowed only when the repository's rules are met. A **merge commit** keeps every commit and adds one that joins them. **Squash and merge** turns the whole pull request into one commit |

A **draft pull request** is one marked not ready. It cannot be merged, and code owners, the people named as responsible for certain files, are not asked to review it until it is marked ready. It is a good place for a change that is still being investigated.

### How do I open one through the agent?

You say what you want, and the agent runs `gh`. The `gh` command-line tool talks to GitHub, and the agent can run it for you once you have signed in with `gh auth login`. You say "push this branch and open a draft pull request against `main`, using the template". The agent runs `git push -u origin weekend-rule`, then `gh pr create --draft --base main`. Later, `gh pr checks` shows the checks and `gh pr merge` merges. Each of these acts on a shared repository, so read each one before you approve it, as in [15.2](git-through-the-agent.md). After `main`'s first push, pushing to `main` directly is the one to refuse, because every change goes through a pull request.

### Can I use the buttons in my app?

Yes, with the same care. Some desktop apps can also open the pull request for you, show its checks beside the session, and post review comments. That is convenient, and it changes none of the rules. A button that merges when the checks pass, or that posts an approval, acts with your account, exactly as if you had typed the command. Click it only when you would have approved the command ([15.9](approval-scaled-by-risk.md)). [15.11](both-ai-vendors.md) lists each app's controls.

### Public or private?

Public for this lab, private for real work. A repository can be public, which anyone can read, or private. Some protections this chapter teaches, such as required checks[^github-rulesets] and code owners on a private repository, need a paid GitHub plan.[^github-protected-branches] The lab uses a public repository on a free account, because every name and number in Brightline's data is made up. In real work, private code belongs in a private repository on a plan that can protect it.

**At work.** Ana's branch `weekend-rule` is ready for others to see. She asks the agent to push it and open a draft pull request. She writes the title herself: "Weekend rule behind a flag, off by default". She links the change brief, a short file kept in the repository ([15.5](evidence-before-the-pr.md)), in the description. The page lists its commits, three changed TypeScript files, one changed Python file and two new test files. The checks start running before anyone has read a line.

**The operating rule:** every change reaches `main` through a pull request whose description says what it is for, how it was tested and how to undo it.

![The branch weekend-rule, committed on your computer, is pushed to GitHub, then opened as a pull request into main. The pull request page lists description, files changed, commits, discussion and review, and checks. It ends with merge when ready: required checks pass, required approvals are in place, and the repository's rules are met.](img/pull-request-anatomy.png)

*Figure 15.7. From your computer to a pull request. The branch is pushed, and the pull request gathers purpose, diff, discussion, checks and the decision on one page.*

**Practice it.** [Practice: GitHub and the pull request](both-ai-vendors.md#practice-github-and-the-pull-request), in your own tool, ten minutes, and a few more the first time, to set up `gh`.

[^pro-git-remote-branches]: Pro Git, Remote Branches.
[^github-rulesets]: About rulesets, GitHub.
[^github-protected-branches]: About protected branches, GitHub.