Creating a Pull Request
Opening a Pull Request is a five-minute act that determines the next few hours of your reviewer’s life. A good PR is easy to review, easy to merge, and easy to revert. This page walks through the mechanics on GitHub, then shows the GitHub CLI and GitLab equivalents.
Prerequisites
You have a feature branch with one or more commits.
You’ve pushed that branch to a remote you have access to.
You know which branch you want to merge into (the base — usually
main).
Step 1 — Push your branch
Publish the branch
git switch -c add-csv-export # ... commits ... git push -u origin add-csv-export # branch 'add-csv-export' set up to track 'origin/add-csv-export'
Step 2 — Find the “Compare & pull request” button
Right after pushing a new branch, GitHub shows a yellow banner on the repo home page:
GitHub UI
add-csv-export had recent pushes 14 seconds ago [ Compare & pull request ]
Click it and skip to step 4. If you miss the banner, go to the Pull requests tab and click New pull request manually.
Step 3 — Pick base and compare
Base — the branch you want the changes to land in. Usually
main.Compare — the branch with your new commits.
For fork-based contributions: base =
upstream-org/repo:main, compare =your-username/repo:feature-branch.
Step 4 — Write the title and description
The title is your headline; the description is the article. Spend two minutes here — the time is recouped many times over in review.
A good PR description template
## What Add a CSV export button to the reports page. ## Why Closes #214. Customers asked for this in 11 separate support tickets last month; finance teams want it for spreadsheet workflows. ## How to test 1. Navigate to /reports 2. Click "Export CSV" in the top-right 3. Open the downloaded file in Excel — verify columns and totals match the table ## Notes - Reuses the existing exportService — no new dependencies. - Streaming is intentional: 50k-row exports were blowing the heap. Closes #214
See the dedicated commit messages page for guidance on titles — the same imperative-mood, short-headline advice applies to PR titles.
Step 5 — Sidebar metadata
Reviewers — request review from individuals or teams. Code owners are auto-added if a CODEOWNERS file matches.
Assignees — who owns landing this PR (often just you).
Labels — categorise (
bug,feature,breaking-change, etc.).Projects / Milestones — link to roadmaps and release groupings.
Linked issues — explicitly close issues on merge.
Step 6 — Allow edits by maintainers
On fork-based PRs, tick Allow edits by maintainers. Reviewers can then push small fixes directly to your branch (typo fixes, lint corrections) without round-tripping through you.
Step 7 — Open it
Click Create pull request (or Create draft pull request for a WIP). CI starts running. Reviewers get notified. You can keep pushing to the same branch — every push updates the PR.
Mentioning people
In the description or comments
@alice please take a look at the streaming change @acme-co/frontend-team — heads up, this touches shared components cc @bob for context
GitHub CLI: gh pr create
Open a PR without leaving the terminal
# Interactive — prompts for title, body, base gh pr create # One-shot gh pr create \ --title "Add CSV export" \ --body "Closes #214. See description in commit message." \ --base main \ --reviewer alice,@acme-co/frontend \ --label feature \ --assignee @me # Use the commit message as the body, skip all prompts gh pr create --fill # Open as a draft gh pr create --draft --fill
GitLab equivalent
Using the glab CLI
glab mr create \ --title "Add CSV export" \ --description "Closes #214" \ --target-branch main \ --assignee alice \ --label feature # Or push with -o to open an MR on the next push git push -o merge_request.create -o merge_request.target=main origin add-csv-export
After it’s open
Watch the Checks tab. Fix red checks before pinging reviewers.
Respond to comments with code changes; reply in the conversation thread when you do.
Resolve conversations as you address them. Reviewers re-open if you missed something.
When CI is green and approvals are in, hit Merge (or wait for the merge queue).
Common errors
"There isn’t anything to compare" — your branch hasn’t been pushed, or you’re comparing it to itself.
"Can’t automatically merge — conflicts" — rebase your branch on the base, resolve, push again.
Reviewers don’t see updates — they auto-see new commits, but you might need to re-request review.
CI didn’t run — check the Actions / Pipelines tab for a workflow that requires manual approval for first-time contributors.