Working With GitHub Forks

Why Forks?


At Open SGF, we prefer to only give write access to organizers and volunteers that have been with the org for some time. This is both to ensure that we have trusted people reviewing incoming code and for improved security. The latter is incredibly important as direct write access also gives the ability to trigger CI pipelines and potentially deploy changes to production environments.


Because of that, we recommend that our volunteers use GitHub forks to make their changes. When users create a fork, they have a complete copy of the repository in their own account where they can make any changes they’d like. These changes can then be sent back to the “upstream” in the form of a Pull Request where someone with write access can review and accept the changes.


Working in this model comes with some challenges as the flow is somewhat abnormal to what many developers see day to day on the job. This document has some helpful links/guides to make it easier to work with forks


Terminology


  • Remote: a git concept that represents a remote copy of the repository. A local repository can contain multiple remotes and most commands can specify which remote to operate on (e.g. git pull <remote> or git push <remote>

  • Origin: Git uses this as the default remote name. When running git clone <url> git creates a remote called origin and sets it to point to the url you cloned from

  • Upstream: When working with forks, this is a common name given to a remote that is manually added to point to the original repository the fork was from


Initial Setup


When setting up your fork on a local computer, it’s important to add a reference to the upstream repository as you’ll want to sync changes. GitHub has an excellent guide on how to do this.


Note: If you started by cloning the original repository to your local computer you’ll need to use the git remote rm command to remove the origin remote and then use git remote add to add the proper origin and upstream remotes


Syncing


Syncing is an important step when working with forks. This is the process of pulling in changes from the upstream repository as other code (or even your own) gets merged.

There are several ways to do this. GitHub has another great guide going over the options and how to use them.


Additional Info/Gotchas


Error pushing/pulling after removing/changing a remote. This usually is caused by git not know which remote to push the branch to. Typically this can be fixed with git branch -—set-upstream-to <branch name> while having the branch checked


Additional GitHub Documentation: Many of the guides referenced here come from Working with forks by GitHub. There’s lots of other good details in there that may be helpful