Lesson 15.315.3 GitHub and the pull request

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).

Why are there three mains?

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:

Think of the contract office. The host's main is the signed copy in the office. Your main is the copy on your desk. origin/main is your note of what the office held the last time you checked.

When pull requests merge on the host, only the office copy changes. git fetch updates your note. git pull updates your note and then your desk copy.¹ So before you start new work, ask the agent to switch to main and pull.

Figure 15.6. Three mains in two places. Merged pull requests move GitHub's main. Fetch updates origin/main. Then yours moves forward. --ff-only means move forward only if nothing needs merging, and stop if it does.

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:

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. The first time, the repository has to get onto GitHub: the agent runs gh repo create and pushes main, as you will in Lab 15. After that, you say "push this branch and open a draft pull request against main, using the template". The agent runs git push 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. 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). 15.11 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² and code owners on a private repository, need a paid GitHub plan.³ 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), 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.

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, in your own tool, ten minutes, and a few more the first time, to set up gh.