This workshop provides an overview of what “version control” systems are and how they fit into collaborative coding within your team. Specifically, we are focusing here on an introductory approach to version control that focuses on using GitHub either through a browser or through software installed on your computer. We are always happy to improve workshop content so please don’t hesitate to post an Issue on our GitHub repository if you see clear areas for improvement!
If you’d like to cite these materials, please use the following citation:
Lyon, N.J., Chen, A., and Brun, J. (2025). Collaborative Coding with GitHub (v2.0). Zenodo. https://doi.org/10.5281/zenodo.16966956
To maximize the value of this workshop to you, we recommend that you take the following steps before the day of the workshop. You may have already completed some or all of these steps but please read through and confirm that you’ve done all of the steps that are relevant to you to ensure that all participants arrive with a common foundation of installed programs. If anything is unclear, feel free to reach out to us; our contact information can be found in the “SciComp Team” dropdown menu in the “People” page.
If your institution has a dedicated IT team that has sole power to install software on your computer, you will need to contact them before the workshop to do the installation bits of the prep steps we outline below.
There are a couple of distinct use-cases you might have for GitHub that will affect what preparation you need to do before this workshop. Consider the tabs below and follow all of the numbered steps in the choice that best fits your needs.
Start by creating an account on GitHub. GitHub is how you’ll be able to collaborate with others in a way that tracks changes over time while facilitating a range of project management tools.
Dr. Jennifer Bryan has some nice guidelines for picking a good username so choose carefully when you make your profile. We also recommend adding a picture of yourself so that group members can more confidently identify one another on GitHub.
After following all the previous preparation steps, your setup should now be complete.
The below preparation steps includes some code for making sure everything is installed as it should be. All code is either R code () or is command line code (). In either case, you’ll run all provided code in RStudio. R code should be run in the “Console” tab of RStudio while command line code should be run in the “Terminal” tab of RStudio.
If you get errors with the provided code, double check that you are running it in the right place!
Start by creating an account on GitHub. GitHub is how you’ll be able to collaborate with others in a way that tracks changes over time while facilitating a range of project management tools.
Dr. Jennifer Bryan has some nice guidelines for picking a good username so choose carefully when you make your profile. We also recommend adding a picture of yourself so that group members can more confidently identify one another on GitHub.
Now you should install R on your computer. If you already have R, check that you have at least version 4.0.0 by looking at the “Console” of your IDE of choice.
If your version starts with a “3”, please update R to make sure all packages behave as expected.
Once you have R (ver. ≥4.0), install RStudio. If you already have RStudio installed, you may want to make sure that you’re using a recent version to take advantage of some quality of life improvements that are broadly useful.
You can now install Git! Git is the software that actually does the behind-the-scenes version control operations we’ll cover in this workshop. Installing Git differs slightly depending on your operating system so check out the tabs below for the right option for you. These instructions are modified from Jennifer Bryan’s excellent “Happy Git and GitHub for the useR” ebook.
Run the following command line code.
xcode-select --installFor more detailed instructions, see here.
Install Git for Windows (a.k.a. “Git Bash”). When asked about “Adjusting your PATH environment”, select “Git from the command line and also from 3rd-party software”.
For more detailed instructions, see here.
Install Git via your distro’s package manager (in the Terminal).
If you use Ubuntu or Debian Linux that code is as follows:
sudo apt-get install gitIf instead you use Fedora or RedHat Linux the code is instead:
sudo yum install gitFor more detailed instructions, see here.
Regardless of your operating system, once you’ve installed Git, check that worked with the following command line code. All operating systems should be able to run this code.
which gitRStudio should also be able to detect Git so let’s check from that side too. In RStudio click through the following menus: “Tools” “Global Options” “Git / SVN” (cardboard box icon in left sidebar). If you see a file path under “Git executable” then you are good to go!
If Git was not detected, this may be caused by having your RStudio session open while you installed Git for the first time. In that case, please close and restart RStudio before checking again.
The last step to take before you’re all set for the workshop is to get these components talking to one another! You set a password for your GitHub which is used for logging in to GitHub but to actually put your code changes from your computer up to GitHub you’ll need to authenticate yourself. There are two paths for authentication:
What’s the difference? Essentially, authenticating via token makes many things “just work” while authenticating via SSH will work for some things but in other contexts you would also need to do token-based authentication. For a more complete discussion of the benefits and drawbacks of each, see Dr. Bryan’s “HTTPS versus SSH” page.
Follow the steps of your chosen authentication method in the tabs below.
All of the code chunks for authenticating with a token are R code that should be run in the “Console” pane of RStudio. You may also create a script and run the code from there if you so desire but you’ll likely only need this code once so the script’s value would be short-lived.
# Install the `usethis` and `gitcreds` packages
install.packages(c("usethis", "gitcreds"))
# Create a token (Note this will open a GitHub browser tab)
## See steps 6-10 in GitHub's PAT tutorial (link below)
usethis::create_github_token()Copy your token at the end of the above step. Once you leave the page where your token is displayed you’ll never get to see it again! So if you close that page without copying it you’ll need to make a new one in order to continue.
Once you’ve copied your token, run the code below to save your credentials in RStudio.
# Now, give your token to RStudio
## After you run this line follow the prompts in the "Console" tab of RStudio
gitcreds::gitcreds_set()This line of code will prompt you to paste your token in the “Console” tab. After you do so (and hit “Enter”), your token will be safely stored in RStudio!
You may also find GitHub’s PAT tutorial (this is the link referenced in the first token-authentication code chunk!) or the Happy Git with R PAT tutorial helpful.
All of the code chunks for authenticating with SSH are command line code that should be agnostic to your programming language.
First, we need to check whether you already have SSH keys created on your computer. If you get a message saying that nothing exists or the path doesn’t exist, you do not (yet) have SSH keys.
ls -al ~/.ssh/If you do need to create an SSH key pair you can do so via the command line. When you create a key pair you’ll need to include a descriptive comment to help ‘future you’ if you ever have multiple key pairs in your life. We recommend “lter” plus your GitHub username to keep things simple.
ssh-keygen -t ed25519 -C "lter-github"If you get a warning/error because your system is too old to support the Ed25519 algorithm (that’s the variant recommended by GitHub) you can instead use:
ssh-keygen -t rsa -b 4096 -C "lter-github"Accept the prompt to save the key in the default location by hitting Enter. You will be prompted to enter a passphrase that will be required to access your SSH key later on. This step is technically optional but is considered a best practice. If SSH keys are totally new to you, we recommend skipping the passphrase step.
Once you’ve generated the key pair, follow GitHub’s instructions on adding that key pair to your computer’s ssh-agent (roughly equivalent to a password manager but just for SSH key pairs).
Finally, you need to share the public key with your GitHub self. Once again we’ll refer you to the phenomenal materials generated by Dr. Bryan on this topic.
You may also find GitHub’s SSH documentation or the Happy Git with R SSH tutorial helpful.
After following all the previous preparation steps, your setup should now be complete.
Visual Studio Code (a.k.a. VS Code) is an IDE favored by many software developers. Positron itself is actually a “fork” of VS Code’s software! However, Positron offers some additional functionalities to support R users and–given that most working group members are primarily R coders if they code–Positron is what we will be using in this workshop.
However, if you are a VS Code user, much of the Positron content will actually work for you with some (or potentially no) adjustment.
Start by creating an account on GitHub. GitHub is how you’ll be able to collaborate with others in a way that tracks changes over time while facilitating a range of project management tools.
Dr. Jennifer Bryan has some nice guidelines for picking a good username so choose carefully when you make your profile. We also recommend adding a picture of yourself so that group members can more confidently identify one another on GitHub.
Now you should install R on your computer. If you already have R, check that you have at least version 4.0.0 by looking at the “Console” of your IDE of choice.
If your version starts with a “3”, please update R to make sure all packages behave as expected.
Once you have R (ver. ≥4.0), install Positron. If you already have Positron installed, you may want to make sure that you’re using a recent version to take advantage of the features available in the most recent version.
You can now install Git! Git is the software that actually does the behind-the-scenes version control operations we’ll cover in this workshop. Installing Git differs slightly depending on your operating system so check out the tabs below for the right option for you. These instructions are modified from Jennifer Bryan’s excellent “Happy Git and GitHub for the useR” ebook.
Run the following command line code.
xcode-select --installFor more detailed instructions, see here.
Install Git for Windows (a.k.a. “Git Bash”). When asked about “Adjusting your PATH environment”, select “Git from the command line and also from 3rd-party software”.
For more detailed instructions, see here.
Install Git via your distro’s package manager (in the Terminal).
If you use Ubuntu or Debian Linux that code is as follows:
sudo apt-get install gitIf instead you use Fedora or RedHat Linux the code is instead:
sudo yum install gitFor more detailed instructions, see here.
The last step to take before you’re all set for the workshop is to get these components talking to one another! One reason to use Positron instead of RStudio is because of how much simpler this step is for Positron. Instead of needing to write code, we can do a little authentication dance with buttons in the browser and afterwards, everything will ‘just work.’
To begin, open Positron. You should have a screen that looks something like the below screen capture. Note that you might be in “light mode” depending on your computer settings but that should not affect which buttons to click or where they can be found.
From there, go to the left sidebar and click the branch icon ( ). It should be the third option from the top. Once you are there, click “Clone Repository”.
This should automatically open the search bar in the top middle of Positron and present you with a single option titled “Clone from GitHub”. Click that option.
Once you’ve clicked that option, you should be presented with the following pop up where Positron is telling you that Positron’s GitHub extension wants to talk to the online version of GitHub. Click “Allow”.
Positron will now allow provide you with a code of random letters/numbers that you’ll need to share with GitHub. Helpfully, a new pop-up will appear where one of the options is “Copy & Continue to Github”; click that option.
Once you click “Copy & Continue to Github” button, you should automatically be sent to your default web browser application and be prompted to choose which GitHub account to use. Most users will have only one option so go ahead and click “Continue” next to that profile.
You’ll next need to put in the code that you got from Positron. You should be able to simply paste it in because you just copied it! After you’ve entered the code, click “Continue”.
GitHub will now provide you with a list of the permissions that Positron is asking for and ask you to approve them. These permissions are required for you to work with Positron so feel free to read through them but ultimately you must scroll down and click “Authorize”.
If you are a member of any GitHub organizations, they will be listed below the list of requested permissions but you should just ignore those and scroll past them.
If you have not recently logged in to GitHub, you will be sent to the standard GitHub login page. If you are sent there, log in as normal (i.e., either by using your username/password or with the 2FA option provided by the GitHub Mobile app).
Once you’ve worked through the above step, you should get a confirmation page from GitHub that looks like the following screen capture.
You will know that you’ve followed these steps correctly if, when you return to Positron, the search bar in the top middle (that said “Clone from GitHub” before) now has a list of repositories to which you have access.
After following all the previous preparation steps, your setup should now be complete.
The reproducibility and collaborative benefits of GitHub for working scientists is well appreciated and increasingly well published upon. See below for brief synopses of papers published in this realm that we think may resonate with your team’s disciplinary backgrounds and motivations.
In the ecology and evolutionary biology sphere, Pereira Braga et al. published “Not just for programmers: How GitHub can accelerate collaborative and reproducible research in ecology and evolution” in Methods in Ecology & Evolution. This paper is a phenomenal resource for ecologists and evolutionary biologists who are considering the value of GitHub to them in and outside of a working group context. The authors identify 12 uses of GitHub for the EEB community and arrange them by technical difficulty (ranging from beginner to advanced) and degree of collaboration (low to high). We have embedded this paper’s second figure in this website below as it is a neat summarization of many of their central points. That said, we definitely recommend reading (and citing!) Pereira Braga et al. 2023 for more detail than we’ve included in this blurb.
If you are concerned about the technical side of GitHub for yourself and/or your lab group, we recommend focusing on the lower technical difficulty benefits of GitHub (see the blue bars). We also think that some of the intermediate technical difficulty uses (orange bars) may be relevant to working group priorities and goals.
