15.3 GitHub and the pull request
- Approved by
- Panaversity ·
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:
| 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.1
Figure 15.6. Three mains 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) |
| 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) |
| 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. 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 checks2 and code owners on a private repository, need a paid GitHub plan.3 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.
Check yourself
Question 1 / 8
0 answered
A teammate says "pull the latest". What does pulling do?
Sources
- Owner
- Panaversity