GitHub: A Practical Guide to Branches and Pull Requests

June 10, 2025

A Common “simple” workflow

I often see this sort of workflow:

git add .
git commit -m "asd"
git push

Many System Administrators and DevOps engineers start with this simple approach.

Being the sole user of version control they feeli satisfied with just having their code versioned.

The problem arises the day another team member joins or (what’s more likely) you join a larger team. This is important because larger teams require more structure and coordination to work effectively with version control, and will most likely require this from you before you get to work.

GitHub Pull Requests rules

When it comes to GitHub; you could argue that the Pull Request is GitHub’s greatest feature (maybe GitHub actions are the second greatest feature hehe).

Let’s look at a simple workflow that utilizes this feature.

It’s designed to promote collaboration and has features that promotes DevOps:

Knowledge Sharing
Code Review
Testing
Continuous Integration
Documentation
Team Collaboration
Audit Trail

And much much more!

The workflow (git kata)

Git provides a structured way to manage changes, review them, and roll back if needed using git branches.

A Team Workflow

Use this in a team environment where you have access to the repository.

Update your local main:
```
git checkout main
git pull origin main
```
Create and switch to new branch:
```
git checkout -b feature-branch
```

Make your changes and commit:

git add .
git commit -m 'Your commit message'

Push to remote:
```
git push -u origin feature-branch
```
Create PR on GitHub from your branch to main

After PR is merged, cleanup:

git checkout main
git pull origin main
git branch -d feature-branch

Think of branches like snapshots of your system. Each branch is a safe place to make changes without affecting the main system.

Open Source Forking Workflow

When contributing to open source projects, you won’t have direct access to the main repository.

This is where forking comes in - it’s like creating your own copy of the project that you can modify freely.

Think of it as getting your own sandbox to play in, while still being able to share your changes with the original project.

Fork the repository on GitHub
- Click the “Fork” button in the top-right corner
- This creates your own copy of the repository under your GitHub account

Clone your fork to your local machine:

git clone https://github.com/your-username/repo.git

Add the original repository as upstream:

git remote add upstream https://github.com/original-owner/repo.git

Keep your fork in sync

This is crucial - you need to make sure your local copy, your fork, and the original repository are all on the same page.

Always make sure your fork is up to date before starting new work. You’ll minimize merge conflicts this way. This should be something you think about every time you open your IDE.
```
git checkout main
git pull origin main    # Get changes from your fork
git pull upstream main  # Get changes from original repo
```
Create your feature branch:
```
git checkout -b feature-branch
```

Make your changes and push to your fork:

git add .
git commit -m 'Your changes'
git push -u origin feature-branch

Create a Pull Request on GitHub
- Go to your fork on GitHub
- Click “Compare & pull request”
- Select your feature branch to merge into the original repository’s main branch

After your PR is merged, clean up:

git checkout main
git push -d origin feature-branch  # Delete remote branch
git branch -d feature-branch       # Delete local branch
git remote prune origin            # Clean up stale references

When to Use Each Workflow

Team Workflow: Use when you have direct access to the repository and are working with a team
Forking Workflow: Use when:
- Contributing to open source projects
- You don’t have write access to the main repository
- You want to experiment with changes without affecting the main repository
- You want to maintain your own version of a project

What do you mean Kata?

I first heard the term Kata from Michael Lombardi in his Getting GitHub repo (which I highly recommend you check out).

The idea being a small daily exercise to help you get used to the workflow and build memory through repetition.

In this case, the workflow I’ve described above can be used as a daily practice:

Create a new branch
Make a small change
Create a PR
Get it reviewed and merged, or removed by yourself if it’s not needed and is only for learning purposes etc
Clean up

This is a safe, simple and powerful way to get used to the workflow and build memory through repetition, which is one of my favorite ways to learn something new!

If your repo contains code that you value
You want to collaborate with others
You want to learn git and github
You want to be a better developer
If you’re using git + github at work

Do:

Practice the workflow daily
Create a tool to help you remember the sequence of commands at first (I created my own python script)