Skip to content
The AI Agent Factory

15.3 GitHub and the pull request

Approved by
Panaversity ·
15 min read

In everyday life. A team keeps the signed copy of a contract in a shared office, not on anyone's desk. 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 office copy change.

What you will learn. How to ask your agent to share a branch and open a pull request, and what each of the six parts of a pull request is for.

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

Where does a team keep the good copy?

On a server that everyone on the team can reach, as the office keeps the signed contract. Git itself works on your computer, so the practice folder from 15.1 exists only on your desk. A team needs one copy that all of them see. GitHub is the most common service that keeps one, and this chapter uses it. GitLab and others work the same way.

Two words describe it:

  • The shared copy is called a remote: a copy of the repository somewhere else.
  • Pushing sends your commits to the remote. It is carrying your pages to the office.

What is a pull request?

It is the draft you bring to the office: a page on GitHub that asks to add one branch to main. You push a branch, and then you open the page for it. The page has six parts:

PartWhat it is for
Title and descriptionSays what the change is for, how it was tested, its risk and how to undo it
Files changedThe diff. A reviewer can comment on a single line
CommitsThe steps of the change, one by one
ConversationReviewers' comments, and the answers to them
ChecksThe automated runs, each one passing, failing or only advising
MergeThe decision. It is allowed only when the repository's rules are met

This page is a pull request: a request to merge a branch into main, on a page where the change is described, checked, discussed and decided. Merging is the signature. It carries the branch's commits into main, and only then does the shared copy change. GitLab calls the same page a merge request.

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.

Figure 15.6. 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.

How do I open one through the agent?

You say what you want, and the agent runs gh, a tool that lets it talk to GitHub. You sign in to gh once. Then, for a change, you say: "Push this branch and open a draft pull request against main." A draft is a pull request marked not ready yet.

WhenThe agent runsWhat it does
Once, the first timegh repo create, then a push of mainPuts the repository on GitHub
For each changegit push origin weekend-ruleSends the branch to GitHub
Thengh pr create --draft --base mainOpens a draft pull request against main
Latergh pr checksShows the checks
Latergh pr mergeMerges

Some of these only read. A push, a gh pr create and a gh pr merge change the shared repository, so read each one before you approve it, as in 15.2. After the first push of main, a push straight to main is the one to refuse. Nobody changes the office copy without bringing a draft: every change goes through a pull request.

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". In the description she links the change brief, a short file kept in the repository (15.5). The page lists its commits and the files they changed. The checks start running before anyone has read a line.

Try it

In your practice folder from 15.1, read a real pull request through the agent, and find its six parts. You need a free GitHub account, and a few more minutes the first time.

The pull request is a finished one. This book's labs are kept in a public repository on GitHub, panaversity/agentfactory-v2-resources, which belongs to Panaversity, the book's publisher. Pull request 150 added Lab 13 to it. Because it is public and already merged, you can read every part of it and change nothing.

  1. Send: "Check whether the gh tool is installed on this computer and signed in to GitHub. If it is not, walk me through it, one step at a time. I will sign in in my browser." Never type a password or a token into the chat. If you get stuck, the steps are in the first section of field-guide-code-review-setup.md. That file is in the brightline-lab-ch15 folder you unzipped, beside brightline-ap.
  2. Send: "Show me pull request 150 of the public repository panaversity/agentfactory-v2-resources. Change nothing."
  3. Send: "Now list the files it changed, and show me its checks. Change nothing."
  4. In your notes, match what you saw to the six parts in the table above. The agent reported no checks, because that repository has none set up. Write what that means for a merge there.
  5. Send: "Does this folder have a remote? Change nothing."

What you should see. The title "Lab 13: the due-date calculator in two languages", the state MERGED, its description, and a long list of files under labs/brightline-lab-ch13/. With no checks set up, no check could stop a merge there: only a person's decision stood between that branch and main. Your own folder has no remote. It exists only on your computer until its first push, which you do in Lab 15.

How each app helps you open and follow a pull request:

Create PR uses gh. The pull request then shows in the Changes card with the status of its checks.1

Use gh through the agent. From the app you can also post comments and submit a review on the pull request. Reviewing in the chat posts nothing. Posting from the pull request's view sends a comment to GitHub at once.2

Use gh through the agent. OpenCode's changelog names no pull request controls.3


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.

Other GitHub words you will meet

You do not need these to finish this lesson. Come back to this table when a later lesson or the lab uses one.

WordWhat it means
originThe name git usually gives the remote
PullBringing the remote's new commits to your computer. It is the opposite of a push
Your main and GitHub'sThere are two. When a pull request merges, only GitHub's main moves. Yours moves when you pull, so ask the agent to switch to main and pull before new work4
origin/mainGit's note, kept on your computer, of where GitHub's main was the last time git looked. Looking is called a fetch
CloneMaking a full copy of a remote repository on your computer
ForkA copy of a repository that someone outside the team keeps on GitHub. A pull request from a fork gets more care, because its code and its text come from outside the team (15.9)
Draft pull requestA pull request marked not ready. It cannot be merged, and its required reviewers, the code owners (15.9), are not asked yet
Merge commitA way to merge that keeps every commit of the branch. Squash and merge turns them into one commit
Public or privateAnyone can read a public repository. On a private one, some protections, such as required checks,5 need a paid GitHub plan.6 The lab uses a public one, because its data is made up

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.

Figure 15.7. main in two places. Merged pull requests move GitHub's main. A fetch updates the note, origin/main. Then your main moves forward.

Next. 15.4 asks why a change needs more than one kind of check.

Check yourself

Question 1 / 9

0 answered

A teammate says "pull the latest". What does pulling do?

  1. Use Claude Code Desktop, Anthropic.↑
  2. Code review, OpenAI.↑
  3. Changelog, OpenCode.↑
Owner
Panaversity