GitHub Pull Requests – Complete Guide to Code Reviews
A developer completes a feature on their local machine. The code works, and the developer pushes it to GitHub. Should the changes go directly into the main branch?
In a professional development team, usually not. Another developer should review the changes before they become part of the shared codebase.
1. What Is a GitHub Pull Request?
A Pull Request is a request to bring changes from a source branch into a target branch.
For example, imagine an Employee Management Application. A developer is working on a new employee registration feature. Instead of changing the main branch directly, the developer creates a separate branch.
- Base branch: The branch that should receive the changes, commonly main.
- Head branch: The branch containing the developer's changes, such as feature/employee-registration.
- Pull Request: The proposal to merge the head branch into the base branch.
2. Why Do Development Teams Use Pull Requests?
Pull Requests help teams review changes before those changes become part of the shared application.
- Find defects early: Reviewers can identify bugs before merging.
- Improve code quality: Developers can discuss readability, design, and maintainability.
- Share knowledge: Team members understand changes made by others.
- Track decisions: Comments and approvals remain connected to the changes.
- Automate validation: Build pipelines and tests can run against proposed changes.
- Protect important branches: Repository rules can require reviews and successful checks.
3. Understand the Pull Request Workflow
Let's follow one feature from development to merge. A developer creates an employee registration feature and proposes it for the main branch.
A Pull Request is an iterative workflow. Review feedback can send the changes back for another update.
4. Create a Feature Branch and Push Your Changes
First, make sure your local repository is updated. Then create a separate branch for the feature.
git switch main
git pull origin main
git switch -c feature/employee-registration
# Make your application changes
git status
git add .
git commit -m "Add employee registration feature"
git push -u origin feature/employee-registration
These commands create a feature branch, save the changes, and publish the branch to GitHub.
5. How to Create a Pull Request on GitHub
After pushing your branch, open the repository on GitHub.
Navigate to the GitHub repository containing your feature branch.
Select the option to create a new Pull Request.
Choose main as the base and feature/employee-registration as the compare branch.
Confirm that the proposed changes contain the intended files and commits.
Explain what changed, why it changed, and how the reviewer can test it.
Submit the proposal and request reviews from the appropriate team members.
Example Pull Request description
Title:
Add employee registration feature
Description:
## What changed?
- Added employee registration API.
- Added request validation.
- Added employee persistence logic.
## Why is this change needed?
Allows administrators to register new employees.
## How to test?
1. Start the application.
2. Send a valid registration request.
3. Verify the employee record is created.
4. Test invalid and duplicate employee details.
## Checklist
- [x] Code builds successfully
- [x] Input validation added
- [x] Tests updated
- [ ] Reviewed by another developer
6. Understand the Main Sections of a Pull Request
GitHub provides several views to help authors and reviewers understand the proposed changes.
| Section | Purpose |
|---|---|
| Conversation | Shows the description, comments, review activity, and timeline. |
| Commits | Shows the commits included in the Pull Request. |
| Checks | Shows automated build, test, and validation results. |
| Files changed | Displays the code differences between the branches. |
| Merge area | Shows whether the Pull Request can be merged and which requirements remain. |
7. What Is a Code Review?
A code review is the process of examining another developer's changes before merging them.
The reviewer checks whether the implementation solves the intended problem. They also look for defects, security issues, performance problems, and maintainability concerns.
What should a reviewer check?
- Correctness: Does the code meet the requirement?
- Readability: Can another developer understand the implementation?
- Error handling: Are invalid inputs and failure scenarios handled?
- Security: Is user input validated? Are secrets protected?
- Performance: Does the change introduce unnecessary database calls or expensive operations?
- Testing: Are important success and failure scenarios covered?
- Compatibility: Could the change break existing functionality or APIs?
8. How to Review Code in GitHub
Open the Pull Request and select the Files changed tab. GitHub displays the differences between the base and head branches.
Understand the diff
public decimal CalculateSalary(decimal basicSalary)
{
return basicSalary;
}
public decimal CalculateSalary(
decimal basicSalary,
decimal allowance)
{
return basicSalary + allowance;
}
The reviewer should check whether the new allowance is part of the business requirement. They should also check validation, tests, and any affected callers.
Line-level comments
You can add a comment to a specific line in the changed code. This keeps the discussion connected to the exact implementation.
For example:
Suggested changes
When you know the exact correction, you can create a GitHub suggestion block. The author can apply the suggested code directly from the review.
This is useful for small corrections, such as variable names, simple conditions, or formatting. For larger changes, explain the design concern and discuss the appropriate solution.
9. Understand the Three Review Decisions
After examining the changes, a reviewer submits a review decision.
| Decision | Meaning | When to use it |
|---|---|---|
| Comment | Provides feedback without explicitly approving or requesting changes. | When you want to discuss or clarify something. |
| Approve | Signals that the changes are ready for merging. | When the implementation meets the review requirements. |
| Request changes | Flags feedback that should be addressed before merging. | When important corrections are needed. |
To submit a review, add a summary comment, choose the decision, and select Submit review.
10. How Does a Developer Address Review Feedback?
Suppose a reviewer finds missing validation in the employee registration feature. The author should update the same feature branch rather than create an unrelated Pull Request.
# Switch to the feature branch
git switch feature/employee-registration
# Update the implementation and tests
git add .
git commit -m "Add employee registration validation"
# Push the new commit
git push origin feature/employee-registration
GitHub updates the existing Pull Request when new commits are pushed to its head branch.
The reviewer can then inspect the new changes and submit another review. This process continues until the team is satisfied.
11. What Are Automated Checks in a Pull Request?
Code review is not limited to manual inspection. Teams often connect automated checks to Pull Requests.
For example, a GitHub Actions workflow can run when someone opens a Pull Request or pushes new commits to its branch.
name: Pull Request Validation
on:
pull_request:
branches:
- main
jobs:
build:
runs-on: ubuntu-latest
steps:
- name: Checkout source
uses: actions/checkout@v4
- name: Setup .NET
uses: actions/setup-dotnet@v4
with:
dotnet-version: '8.0.x'
- name: Restore dependencies
run: dotnet restore
- name: Build application
run: dotnet build --no-restore
- name: Run tests
run: dotnet test --no-build
This is an illustrative workflow for a .NET 8 repository. Adjust the SDK version and project commands to match your solution.
When configured, GitHub displays the workflow result in the Pull Request's Checks section.
12. What Are Draft Pull Requests?
A Draft Pull Request is a proposal that is not yet ready for formal review or merging.
Developers use drafts when they want early feedback or need to show work in progress. A draft communicates that the implementation is still being developed.
When the work is ready, the author can mark the Pull Request as ready for review.
When should you create a draft?
- The feature is still under development.
- You want early feedback on the design.
- You need to share progress with the team.
- You want to validate an approach before completing the implementation.
13. How to Merge a Pull Request
Once the required reviews and checks are satisfied, an authorised team member can merge the Pull Request.
GitHub commonly provides three merge methods.
| Merge method | How it works | Result |
|---|---|---|
| Create a merge commit | Combines the branch histories with a merge commit. | Preserves the branch's individual commits and merge history. |
| Squash and merge | Combines the Pull Request's commits into one commit. | Creates a simpler commit history on the base branch. |
| Rebase and merge | Replays the commits onto the base branch. | Creates a linear history without a merge commit. |
The repository's settings determine which merge methods are available. The team should choose a consistent strategy that fits its workflow.
14. What Happens When There Is a Merge Conflict?
A merge conflict happens when Git cannot automatically combine changes. This can happen when two branches modify the same lines or when Git cannot safely determine how to combine the changes.
For example, another developer may update the employee validation logic in the main branch while your feature branch changes the same code.
You must resolve the conflict and verify the final implementation before merging.
git switch feature/employee-registration
git fetch origin
git merge origin/main
# Resolve the conflicting files manually
git status
git add .
git commit -m "Resolve merge conflicts with main"
git push origin feature/employee-registration
After resolving the conflict, run the relevant tests and check the Pull Request again.
15. Branch Protection and Required Reviews
Repository administrators can configure rules that protect important branches, such as main.
Depending on the repository configuration, these rules can require:
- Pull Requests before changes are merged.
- A minimum number of approving reviews.
- Code owner approval for specific files.
- Successful status checks.
- Resolution of review conversations.
- Restrictions on who can push or merge changes.
For example, a team may require one approval and successful build and test checks before merging into its main branch.
16. Pull Request Best Practices
For Pull Request authors
- Create small, focused Pull Requests.
- Use meaningful titles and descriptions.
- Link related issues when applicable.
- Remove unrelated changes before submitting.
- Add tests for important behaviour.
- Respond to review comments respectfully.
- Keep the feature branch updated when needed.
For reviewers
- Understand the problem before reviewing the code.
- Review one file at a time.
- Focus on correctness, security, and maintainability.
- Explain why a change is needed.
- Suggest improvements with practical examples.
- Separate critical defects from optional suggestions.
- Submit a clear review summary.
17. Common Pull Request Mistakes
| Mistake | Better approach |
|---|---|
| Submitting a very large Pull Request | Break the work into smaller, focused changes. |
| Using unclear titles | Describe the actual feature or fix. |
| Ignoring automated failures | Investigate and fix failed checks before merging. |
| Approving without reading the diff | Review the implementation and relevant tests. |
| Using comments without context | Explain the problem and expected improvement. |
| Merging with unresolved concerns | Address required feedback and repository rules. |
| Forgetting to test conflict resolution | Run relevant tests after resolving conflicts. |
18. Practical Exercise – Create and Review a Pull Request
Let's practise the complete workflow using an Employee Management Application.
- Create a repository named employee-management.
- Create a branch named feature/employee-registration.
- Add an employee registration API or a small feature.
- Commit and push your changes.
- Create a Pull Request targeting main.
- Add a meaningful description and testing steps.
- Ask another developer to review the changes.
- Add a line-level comment or suggested change.
- Update the feature branch based on feedback.
- Run the automated checks and merge when requirements are satisfied.
After completing the exercise, you should understand how teams use Pull Requests to collaborate on shared codebases.
19. GitHub Pull Request Interview Questions
A Pull Request proposes merging changes from one branch into another. It supports code review, discussion, and validation before merging.
The base branch receives the changes. The head branch contains the proposed changes.
Comment, Approve, and Request changes. Each communicates a different review outcome.
A draft communicates that the work is not ready for formal review or merging. A normal Pull Request can be reviewed as ready for consideration.
The existing Pull Request is updated with the new commit. You do not need to create another Pull Request for the same branch comparison.
No. Required checks, additional approvals, permissions, merge conflicts, and repository rules can still prevent merging.
Squash and Merge combines the Pull Request's commits into one commit. A merge commit combines branch histories while preserving the individual commits.
GitHub does not allow authors to approve their own Pull Requests.
They are configured validation checks that must pass before a Pull Request can be merged into a protected branch.
Smaller Pull Requests are easier to understand, review, test, discuss, and maintain.
20. Key Takeaways
- A Pull Request proposes changes from one branch to another.
- Code reviews help improve quality and reduce defects.
- Reviewers can comment on lines and suggest exact changes.
- Comment, Approve, and Request changes are the main review decisions.
- New commits update the existing Pull Request.
- Automated checks validate code before merging.
- Branch protection can enforce reviews and status checks.
- Merge strategies affect the resulting Git history.
Conclusion
GitHub Pull Requests are an important part of professional software development. They help developers discuss changes, review implementations, and maintain a reliable codebase.
Understanding the complete Pull Request workflow is useful for every developer working with a team. Practise creating Pull Requests, reviewing code, responding to feedback, and merging changes.
In the next article, we will explore GitHub Issues and learn how teams track bugs, tasks, feature requests, and project discussions.