LATEST 🚀 Welcome to Upgradix by Shrash Studio – Your destination for free technology learning and career growth.
🕘 Updated:
Git & GitHub

GitHub Collaboration – Fork, Upstream and Open Source Workflow

Open source means the source code is publicly available for people to study, use and contribute according to its licence. Developers can suggest improvements without directly changing the original repository.

GitHub Collaboration – Fork, Upstream and Open Source Workflow

Imagine finding a useful open-source project on GitHub. You notice a bug and know how to fix it. However, you do not have permission to change the original repository. How can you contribute your solution?

This is where GitHub collaboration becomes important. Developers use forks, branches, remote repositories, and pull requests to work together without directly changing another developer's code.

In this article, you will learn:
  • What a fork is and how it differs from a clone.
  • What origin and upstream mean.
  • How to contribute to an open-source project.
  • How to keep your fork synchronised with the original repository.
  • How to create a branch, push changes, and open a pull request.
  • How to handle reviews, conflicts, and contribution best practices.

1. Why Do Developers Need GitHub Collaboration?

Modern software projects are rarely developed by one person. Multiple developers work on different features, fixes, and improvements.

Consider an open-source payment validation library. A developer discovers that a validation rule does not handle a particular input correctly. The developer wants to fix the issue and share the improvement with the project maintainers.

Directly changing the original repository may not be possible. The repository owner controls who can push changes to it.

GitHub provides a collaboration workflow that solves this problem. A contributor creates a separate copy, makes changes, and proposes those changes to the original project.

Common collaboration scenarios

  • Contributing bug fixes to open-source projects.
  • Adding features to an existing application.
  • Improving documentation and examples.
  • Reviewing code written by other developers.
  • Maintaining a personal fork of an external project.
  • Working with distributed development teams.

2. What Is a Fork in GitHub?

A fork is a GitHub-hosted copy of another repository under your own GitHub account or organisation.

It gives you a separate repository where you can experiment, create branches, commit changes, and push your work.

A fork does not automatically give you permission to modify the original repository. Your changes remain in your fork until you propose them through a pull request.

Example

Assume the original project belongs to an organisation:

https://github.com/open-source-team/payment-validator

You fork it into your account:

https://github.com/your-username/payment-validator

Both repositories contain their own repository history and branches. You can now make changes in your copy without directly modifying the original project.

Important: A fork is a GitHub repository relationship. It is not the same as creating a local copy using git clone.

3. Fork vs Clone: What Is the Difference?

These two operations are related, but they solve different problems.

Understanding fork and clone
Fork Clone
Creates a GitHub-hosted copy of a repository. Creates a local copy on your computer.
Performed through GitHub. Usually performed using the Git command line or a Git client.
Creates a repository under your account or organisation. Creates a working directory on your machine.
Useful when you cannot directly push to the original repository. Useful when you need to work with repository files locally.
Can be used as the source of a pull request. Does not create a GitHub repository by itself.

In a typical open-source contribution, we use both operations:

  1. Fork the original repository on GitHub.
  2. Clone our fork to the local machine.
  3. Make changes locally.
  4. Push changes to our fork.
  5. Open a pull request against the original repository.

4. What Are Origin and Upstream?

This is one of the most important concepts in fork-based collaboration.

A remote is a named reference to another Git repository. It allows Git to communicate with repositories hosted elsewhere.

When you clone your fork, Git normally creates a remote named origin.

In a fork-based workflow, developers commonly use two remotes:

  • origin: Your fork on GitHub. You usually push your changes here.
  • upstream: The original repository. You usually fetch its latest changes from here.

Example repository arrangement

The original repository is forked into a contributor account. The contributor clones their fork locally. Changes are pushed to origin, while updates are fetched from upstream. Original Repository open-source-team/payment-validator Fork Your GitHub Fork your-username/payment-validator Clone Local Repository Your computer Push to origin Fetch upstream

Your fork is the destination for your changes. The upstream repository is the source of the original project's updates.

Why do we need two remotes?

Your fork is where you have permission to push changes. The original repository may not allow direct pushes from contributors.

You still need the original project's latest changes. The upstream remote provides access to those updates.

Remote responsibilities
Remote Points to Common operation
origin Your fork git push origin
upstream Original repository git fetch upstream

5. Complete Open-Source Contribution Workflow

Now let's follow a realistic example. We will contribute a validation improvement to an open-source payment library.

Assume the original repository is:

https://github.com/open-source-team/payment-validator.git

Replace the example repository and username with the actual project details when practising.

Step 1: Fork the original repository

Open the original repository on GitHub. Select the Fork option and create a copy under your account.

After the fork is created, your repository URL will look similar to this:

https://github.com/your-username/payment-validator

You now have your own GitHub repository based on the original project.

Step 2: Clone your fork

Open a terminal and clone the repository that belongs to your account.

Clone your fork

git clone https://github.com/your-username/payment-validator.git
cd payment-validator

This creates a local working directory. Git also configures the cloned repository as the origin remote.

Check the configured remote

git remote -v

Example output

origin  https://github.com/your-username/payment-validator.git (fetch)
origin  https://github.com/your-username/payment-validator.git (push)

Step 3: Add the upstream remote

Next, connect your local repository to the original project.

Add the original repository

git remote add upstream https://github.com/open-source-team/payment-validator.git

Check both remotes again:

git remote -v

Example output

origin    https://github.com/your-username/payment-validator.git (fetch)
origin    https://github.com/your-username/payment-validator.git (push)
upstream  https://github.com/open-source-team/payment-validator.git (fetch)
upstream  https://github.com/open-source-team/payment-validator.git (push)
Remember: Adding an upstream remote does not grant write permission to the original repository. It only configures a remote reference.

Step 4: Fetch the latest upstream changes

The original project may receive updates while you are working. Fetch those changes before creating your contribution branch.

git fetch upstream

This downloads updated objects and remote-tracking references. It does not automatically merge them into your current branch.

You can inspect the available remote branches using:

git branch -r

For a repository whose default branch is main, you may see:

origin/HEAD -> origin/main
origin/main
upstream/main

Step 5: Synchronise your local main branch

Before starting new work, update your local main branch with the original repository's latest changes.

git switch main
git merge upstream/main

This merges the fetched upstream main branch into your local main branch.

If you prefer a linear history, you can use the following alternative:

git switch main
git rebase upstream/main
Do not run both approaches for the same synchronisation step. Choose merge or rebase based on your team's workflow. Be careful when rebasing commits that other developers already use.

After updating local main, push it to your fork if required:

git push origin main

Step 6: Create a feature branch

Do not make your contribution directly on the main branch. Create a separate branch for the issue or feature.

git switch -c fix/payment-validation-rule

A branch is an independent line of development. It helps keep your contribution separate from other work.

Check your current branch:

git branch --show-current
fix/payment-validation-rule

Step 7: Make and test your changes

Update the relevant source files. For example, you may correct a validation rule in the payment library.

Review the changed files:

git status
git diff

Run the project's tests and follow its contribution guidelines. Do not assume that a successful commit means the code is correct.

Step 8: Commit your changes

Stage only the files related to your contribution.

git add src/PaymentValidator.cs
git commit -m "Fix payment input validation"

A commit records a snapshot of your staged changes in Git history.

Step 9: Push your feature branch to origin

Push the branch to your own fork. The -u option sets the upstream tracking branch for future pushes and pulls.

git push -u origin fix/payment-validation-rule

Your branch is now available on your GitHub fork.

Step 10: Open a pull request

Open your fork on GitHub. GitHub may display a prompt to create a pull request for your recently pushed branch.

When creating the pull request, verify the base and compare repositories carefully.

Correct pull request direction
Pull request field Repository and branch
Base repository open-source-team/payment-validator
Base branch main
Head repository your-username/payment-validator
Compare branch fix/payment-validation-rule

Write a clear title and description. Explain the problem, the solution, and the tests you performed.

Submit the pull request. The original project's maintainers can now review your contribution.

6. Understanding the Complete Collaboration Flow

The following diagram shows how a contribution moves from your local machine to the original project.

A contributor forks and clones a repository, creates a feature branch, commits and pushes changes to their fork, then opens a pull request for maintainers to review and merge. Original Project Upstream repository Your Fork Origin repository Fork Local Repository Your computer Clone Feature Branch Implement and test Push Changes Feature branch to origin Pull Request Request to merge changes Review and Merge Maintainer approval Merged changes

A contributor works in their fork. The original maintainers review and decide whether to merge the proposed changes.

7. What Happens After You Open a Pull Request?

Opening a pull request does not automatically add your changes to the original project.

The project maintainers review your proposed changes. They may ask questions, suggest improvements, or request additional tests.

Common pull request review stages

1. Automated checks

GitHub Actions or another CI system may run tests, builds, formatting checks, and security checks.

2. Code review

Maintainers inspect the changes for correctness, readability, maintainability, and compatibility.

3. Review comments

Reviewers may leave comments on specific lines. They may request changes before approval.

4. Update your branch

Make the requested changes locally. Commit and push them to the same feature branch.

The pull request will reflect the new commits automatically.

5. Approval and merge

When the required checks and reviews are complete, an authorised maintainer can merge the pull request.

Good practice: Keep the pull request focused. A small change with a clear explanation is easier to review.

8. How to Keep Your Fork Updated

Open-source repositories continue to change. Other contributors may merge new features and bug fixes while you work.

Your fork can become outdated. You should periodically synchronise it with the original repository.

Option 1: Update using merge

Fetch the latest changes from upstream and merge them into your local main branch.

git fetch upstream
git switch main
git merge upstream/main
git push origin main

This approach preserves the existing commit history and creates a merge commit when necessary.

Option 2: Update using rebase

You can also replay your local commits on top of the latest upstream main branch.

git fetch upstream
git switch main
git rebase upstream/main
git push origin main

Rebase creates a linear history by replaying commits. It rewrites commit identities for the commits being replayed.

Be careful with rebase: Avoid rebasing a shared branch when other developers depend on its existing commit history. If a push is rejected after a deliberate rebase of your own feature branch, understand the history change before using git push --force-with-lease. Never use force push casually on shared branches.

9. How to Resolve Merge Conflicts in a Contribution

A merge conflict happens when Git cannot automatically combine changes. This often occurs when two branches modify the same part of a file.

For example, your feature branch changes a validation method. The upstream main branch changes that same method before your contribution is merged.

Git needs you to decide how the final code should look.

Example conflict markers

<<<<<<< HEAD
public bool IsValid(string value)
{
    return !string.IsNullOrWhiteSpace(value);
}
=======
public bool IsValid(string value)
{
    return value != null && value.Length > 0;
}
>>>>>>> upstream/main

The markers identify the conflicting sections. They are not valid C# code and must be removed after resolving the conflict.

Typical conflict resolution steps

  1. Open the files reported by Git.
  2. Understand both sets of changes.
  3. Choose or combine the correct implementation.
  4. Remove the conflict markers.
  5. Run relevant tests.
  6. Stage the resolved files.
  7. Complete the merge or rebase operation.

For a merge conflict, the commands commonly look like this:

git status

# Edit the conflicted files and resolve the markers.
git add src/PaymentValidator.cs
git commit

When resolving a rebase conflict, use the following command after staging the resolved files:

git add src/PaymentValidator.cs
git rebase --continue

If you need to cancel an in-progress merge or rebase, use the corresponding abort command:

git merge --abort
git rebase --abort
Run only the abort command for the operation currently in progress. Do not run both as a routine conflict-resolution step.

10. Fork-Based Workflow vs Direct Collaboration

Not every GitHub project requires contributors to fork the repository.

Some teams give developers write access to a shared repository. Those developers can create branches directly inside that repository.

Comparing common GitHub collaboration models
Area Fork-based workflow Shared repository workflow
Repository access Contributor works from a separate fork. Contributor has access to the shared repository.
Feature branch Created in the contributor's fork. Created in the shared repository.
Push destination Usually the contributor's origin. Usually the shared repository's remote.
Pull request From the fork to the original repository. From one branch to another in the same repository.
Typical use Open-source contributions and external contributors. Internal teams and trusted collaborators.

11. Common Mistakes and Best Practices

Common mistakes

  • Confusing origin and upstream: Remember that origin normally points to your fork in this workflow.
  • Working directly on main: Create a feature branch for each contribution.
  • Forgetting to fetch upstream: Your local branch may be behind the original project.
  • Opening a pull request in the wrong direction: Check the base repository and compare repository.
  • Committing unrelated files: Review git status and git diff before committing.
  • Ignoring project guidelines: Read the contribution guide and follow the project's testing requirements.
  • Force pushing shared branches: Rewriting shared history can disrupt other contributors.
  • Leaving conflicts unresolved: Always remove conflict markers and test the final code.
  • Read the repository's README and contribution guidelines first.
  • Check existing issues before starting a contribution.
  • Use descriptive branch names.
  • Keep commits focused and meaningful.
  • Write clear commit messages.
  • Test your changes before opening a pull request.
  • Explain the problem and solution in the pull request description.
  • Respond respectfully to reviewer feedback.
  • Keep your fork synchronised with upstream.
  • Never commit passwords, API keys, tokens, or private configuration.

12. Real-World Production Considerations

Fork-based collaboration is not only about Git commands. It is also about protecting the quality and security of a software project.

Protect the main branch

Important repositories should protect their main branch. Rules can require pull requests, approvals, and successful status checks before merging.

Automate validation

Use CI pipelines to build the application and run automated tests. This helps catch problems before changes reach the main branch.

Protect credentials

Never include production secrets in commits. Use appropriate secret management and GitHub's security features.

Keep contributions traceable

Use meaningful commits and link pull requests to related issues. This helps maintain a clear history of why a change was introduced.

Respect repository ownership

Follow the project's licence and contribution policy. A fork does not remove the original project's licence requirements.

13. Interview Questions and Answers

Q1. What is a fork in GitHub?

A fork is a GitHub-hosted copy of another repository under your account or organisation. It lets you develop changes separately from the original project.

Q2. What is the difference between fork and clone?

A fork creates a repository copy on GitHub. A clone downloads a repository into your local machine.

Q3. What is the difference between origin and upstream?

In a fork-based workflow, origin usually points to your fork. Upstream points to the original repository.

Q4. Why do we use git fetch upstream?

It downloads updates from the original repository. It updates remote-tracking references without automatically merging changes into your current branch.

Q5. Does git fetch automatically update my local main branch?

No. Fetch downloads remote updates. You must merge or rebase the fetched branch to update your local branch.

Q6. What is a pull request?

A pull request proposes changes from one branch or repository to another. It supports code review and discussion before merging.

Q7. Can you push directly to an original repository after forking it?

Only if you have the required write permission. A fork alone does not grant write access to the original repository.

Q8. How do you update your fork with the original repository?

Fetch from upstream, merge or rebase the original main branch into your local main branch, and push the updated branch to origin.

Q9. What happens when you push new commits to a pull request branch?

The existing pull request is updated automatically. You normally do not need to create another pull request.

Q10. When should you use merge instead of rebase?

Use merge when you want to preserve the branch history as it happened. Use rebase when a linear history is preferred and rewriting the relevant commits is safe.

Q11. What is a merge conflict?

A merge conflict occurs when Git cannot automatically combine changes. A developer must resolve the conflicting content and complete the operation.

Q12. Why should we create a feature branch?

A feature branch isolates one change from the main development line. It makes reviews, testing, and collaboration easier.

14. Hands-On Practice

Let's practise the complete fork-based workflow using a public repository you are allowed to contribute to.

Exercise 1: Create your fork

  • Find a suitable open-source repository.
  • Read its README and contribution guidelines.
  • Fork the repository into your GitHub account.

Exercise 2: Configure remotes

  • Clone your fork to your computer.
  • Add the original repository as upstream.
  • Run git remote -v.
  • Identify which remote points to your fork.

Exercise 3: Create a contribution

  • Create a branch named docs/improve-installation-guide.
  • Make a small documentation improvement.
  • Review your changes using git diff.
  • Commit and push the branch.

Exercise 4: Open a pull request

  • Open your fork on GitHub.
  • Compare your branch with the original repository.
  • Verify the base and head branches.
  • Write a clear pull request description.

Exercise 5: Synchronise your fork

  • Fetch changes from upstream.
  • Update your local main branch.
  • Push the updated main branch to origin.
Learning goal: You should be able to explain the complete journey from forking a repository to submitting a pull request without depending on a graphical interface.

15. Conclusion

GitHub collaboration makes it possible for developers to work together across different teams and organisations.

Forking gives contributors their own copy of an existing project. Cloning brings that copy to their local machine. The origin remote points to their fork, while upstream points to the original repository.

Developers create feature branches, make changes, commit their work, and push it to their forks. They then open pull requests so maintainers can review the proposed changes.

Understanding this workflow is an important step towards contributing to open-source projects and working effectively with distributed development teams.

16. Official Documentation and Further Learning

Comments & Ratings (0)

Log in or create a student account to comment and rate this article.

Be the first to comment on this article.