Pull requests
A pull request (PR) proposes merging one branch into another. The PR is the conversation around the diff — review comments, status checks, the merge itself.
Opening a PR
- Push a branch to the repo (or to your fork).
- Visit the repo and click the "Compare & pull request" prompt that appears, or go to Pull requests → "New pull request".
- Pick base (where you want to merge into) and compare (your branch).
- Title + body. Markdown supported. Reference issues with
Fixes #Nto auto-close on merge.
The PR shows the file diff, commit list, and any pre-existing status checks for the head commit.
Reviewing
Open a PR → "Files changed" tab.
- Comment on a line: click the
+in the gutter. - Suggest a change: in the comment, pick "Suggestion" — your inline patch becomes a one-click commit the author can apply.
- Submit a review: "Review changes" → choose:
- Comment — observations, no verdict.
- Approve — green checkmark, counts toward the required- reviewer threshold (if branch protection is on).
- Request changes — red X, blocks merge until dismissed or re-reviewed.
A reviewer can leave many inline comments and bundle them into one review submission.
Merging
Three merge methods (the maintainer picks per repo or per PR if multiple are enabled):
- Merge commit — the classic non-fast-forward merge with a commit that has both parents. Preserves all PR commits as-is.
- Squash and merge — replaces every PR commit with one squashed commit on the base branch. PR title/body becomes the commit message.
- Rebase and merge — replays the PR's commits onto the base. No merge commit; linear history.
shithub detects merge conflicts up front and prevents merge until the PR head is updated. Use the "Update branch" button to merge or rebase the base into your branch (the maintainer picks which strategy is allowed).
Branch protection gates
If the base branch is protected, the merge button is disabled until:
- Required status checks pass (CI integrations report success).
- Required number of approvals collected.
- "Request changes" reviews resolved (dismiss or re-review).
- Conversations resolved (if "Require conversation resolution" is on).
See Branch protection & reviews.
Draft PRs
Open as draft to signal "not ready yet, but visible". Drafts cannot be merged. Convert to "Ready for review" when you want reviewers.
After merge
- The head branch can be auto-deleted (account-level + per-repo setting).
- Linked issues with
Fixes #Nclose automatically. - Watchers + subscribers get notifications.
View source
| 1 | # Pull requests |
| 2 | |
| 3 | A pull request (PR) proposes merging one branch into another. |
| 4 | The PR is the conversation around the diff — review comments, |
| 5 | status checks, the merge itself. |
| 6 | |
| 7 | ## Opening a PR |
| 8 | |
| 9 | 1. Push a branch to the repo (or to your fork). |
| 10 | 2. Visit the repo and click the "Compare & pull request" prompt |
| 11 | that appears, or go to Pull requests → "New pull request". |
| 12 | 3. Pick **base** (where you want to merge into) and **compare** |
| 13 | (your branch). |
| 14 | 4. Title + body. Markdown supported. Reference issues with |
| 15 | `Fixes #N` to auto-close on merge. |
| 16 | |
| 17 | The PR shows the file diff, commit list, and any pre-existing |
| 18 | status checks for the head commit. |
| 19 | |
| 20 | ## Reviewing |
| 21 | |
| 22 | Open a PR → "Files changed" tab. |
| 23 | |
| 24 | - **Comment on a line:** click the `+` in the gutter. |
| 25 | - **Suggest a change:** in the comment, pick "Suggestion" — your |
| 26 | inline patch becomes a one-click commit the author can apply. |
| 27 | - **Submit a review:** "Review changes" → choose: |
| 28 | - **Comment** — observations, no verdict. |
| 29 | - **Approve** — green checkmark, counts toward the required- |
| 30 | reviewer threshold (if branch protection is on). |
| 31 | - **Request changes** — red X, blocks merge until dismissed or |
| 32 | re-reviewed. |
| 33 | |
| 34 | A reviewer can leave many inline comments and bundle them into |
| 35 | one review submission. |
| 36 | |
| 37 | ## Merging |
| 38 | |
| 39 | Three merge methods (the maintainer picks per repo or per PR if |
| 40 | multiple are enabled): |
| 41 | |
| 42 | - **Merge commit** — the classic non-fast-forward merge with a |
| 43 | commit that has both parents. Preserves all PR commits as-is. |
| 44 | - **Squash and merge** — replaces every PR commit with one |
| 45 | squashed commit on the base branch. PR title/body becomes the |
| 46 | commit message. |
| 47 | - **Rebase and merge** — replays the PR's commits onto the base. |
| 48 | No merge commit; linear history. |
| 49 | |
| 50 | shithub detects merge conflicts up front and prevents merge |
| 51 | until the PR head is updated. Use the "Update branch" button to |
| 52 | merge or rebase the base into your branch (the maintainer picks |
| 53 | which strategy is allowed). |
| 54 | |
| 55 | ## Branch protection gates |
| 56 | |
| 57 | If the base branch is protected, the merge button is disabled |
| 58 | until: |
| 59 | |
| 60 | - Required status checks pass (CI integrations report success). |
| 61 | - Required number of approvals collected. |
| 62 | - "Request changes" reviews resolved (dismiss or re-review). |
| 63 | - Conversations resolved (if "Require conversation resolution" is on). |
| 64 | |
| 65 | See [Branch protection & reviews](./branch-protection.md). |
| 66 | |
| 67 | ## Draft PRs |
| 68 | |
| 69 | Open as draft to signal "not ready yet, but visible". Drafts |
| 70 | cannot be merged. Convert to "Ready for review" when you want |
| 71 | reviewers. |
| 72 | |
| 73 | ## After merge |
| 74 | |
| 75 | - The head branch can be auto-deleted (account-level + per-repo |
| 76 | setting). |
| 77 | - Linked issues with `Fixes #N` close automatically. |
| 78 | - Watchers + subscribers get notifications. |