Want to help out or contribute?

If you find any typos, errors, or places where the text may be improved, please let us know by providing feedback using GitHub.

On GitHub open an issue or submit a pull requests by clicking the " Edit this page" link at the side of this page.

9  Connecting to GitHub

One of the best ways of sharing your code (or really, any scientific output, like this website!) is through GitHub. Connecting your Git repository to GitHub is also a great way to collaborate with others and to keep a backup of your work.

So, let’s connect your project to GitHub! 🥳 Thankfully, usethis has a few functions to help us out. Before you can connect your project’s Git repository to GitHub, you need to inform GitHub (authenticate) that you are the owner of your account.

9.1 Authenticating with GitHub

Any time we do anything on the Internet, there is some risk to having our information maliciously hacked. This is no different when using GitHub, so if we can, we should try to be more secure with what we send across the internet. In fact, most functions that relate to Git or using GitHub require using more secure features in order to work. usethis makes this much easier, thankfully, with several functions. The usethis website has a really well written guide on setting it up. Here is a very simplified version of what they recommend that is relevant for what we are doing in this course.

  • Use personal access tokens (PAT, or simply called a “token”) when interacting with your GitHub remote repositories while outside of the GitHub website (e.g. when using R or usethis). PAT’s are like temporary passwords that provide limited access to your GitHub account, like being able to read or write to your GitHub repositories, but not being able to delete them. They are useful because you can easily delete the PAT if you feel someone got access to it and prevent it from being used, unlike your own password which you would have to manually change if it was stolen.
  • Use a password manager to save the PAT for later use. Using password managers is basically a requirement for having secure online accounts, because they can generate random and long passwords that you don’t have to remember.
    • What is a password manager? It is an app or web service that let’s you save or create passwords for all your accounts, like banking or social media. Instead of having to remember multiple passwords used across multiple accounts, or the very insecure approach of one or two passwords for all your accounts, you instead need to remember only one very secure password that contains all your other very secure passwords. Google “password manager” and your operating system (Windows, MacOS) to find possible ones to install or use.
  • Use packages like gitcreds to give usethis access to the PAT and to interact with your GitHub repositories. You normally would use gitcreds every time you restart your computer or after a certain period of time.

You very likely haven’t set up a PAT, but if you are uncertain, you can always check with:

usethis::gh_token_help()
• GitHub host: 'https://github.com'
• Personal access token for 'https://github.com': <unset>
• To create a personal access token, call `create_github_token()`
• To store a token for current and future use, call `gitcreds::gitcreds_set()`
ℹ Read more in the 'Managing Git(Hub) Credentials' article:
  https://usethis.r-lib.org/articles/articles/git-credentials.html

The output is saying the token is <unset>, which means we need to make Git and usethis aware of it. We do that by typing the next function in the Console to create the token on GitHub (if you haven’t created one already).

usethis::create_github_token()

This function sends us to the GitHub “Generate new token” webpage with all the necessary settings checked. Set the “Expiry date” to 90 days (this is a good security feature). Then, click the green button at the bottom called “Generate token” and you’ll have a very long string generated for you that starts with ghp_. Save this token in your password manager. This is the token you will use every time you open up RStudio and interact with GitHub through R. You do not need to create a new token for each R project or package you make, you only need to create one after your current token expires (typically every couple of months), if you’ve forgotten the token or lost it, or if you’ve changed to a new computer.

In the Console, run:

gitcreds::gitcreds_set()

And then copy and paste your token into the prompt in the Console. This token usually gets saved for the day (it gets cached), but after restarting you will need to run the action again. If it asks to replace an existing one, select the “yes” option. Doing this is a bit like using the two-factor authentication (2FA) you often have to do when, for instance, accessing your online bank account or other government website. In this case, you are telling GitHub (when interacting to it through RStudio, like uploading and downloading your changes) that you are who you claim to digitally be.

There is another great helper function that runs a lot of checks and gives some advice when it finds potential problems.

usethis::git_sitrep()

Just to be aware, using this function outputs a lot of stuff, most of which you probably don’t even need to know or don’t even know what it means. That’s ok, since it is meant as a diagnostic tool.

9.2 Linking your project to GitHub

Now that we can authenticate to GitHub that you are digitally you, we can connect our project’s Git repository to GitHub. If you are new to Git and GitHub, we strongly recommend starting your first work project(s) as private, in case you accidentally add files you aren’t supposed to. It will also help get you feeling comfortable with using Git and GitHub. However, for this course, we will be keeping it public. To make it private, we would add the argument private = TRUE to the code below. For now, go to the the Console and run this function to make a public repository:

usethis::use_github()

You may have to manually enter your username and password, even though you used gitcreds::gitcreds_set().

If you have troubles logging in, you may need to update Git.

You might notice the word origin when referring to remotes. The word origin is the default short name to refer to the location of the remote (the GitHub URL). You will probably see this word in many other places to refer to a remote.

This will take your project and upload it to GitHub. Now, whenever you use Git and save your changes to the Git history, whenever you “Push” your changes it will be sent to your project on GitHub. The diagram below shows how it conceptually looks like:

%%{init:{'theme':'forest', 'flowchart':{'nodeSpacing': 20, 'rankSpacing':30}}}%%
graph LR;
    yours(Your local) -->|Push| github(GitHub)
    github -->|Pull| yours
Figure 9.1: Schematic showing a local repository connected to GitHub’s remote repository.

The “Your local” is your own computer. Whenever you “push” to GitHub, it means it will upload your file changes (like synchronizing in Dropbox). Whenever you “pull” from GitHub, it takes any changes made on GitHub and downloads them to your “Local” computer.

Why use GitHub? For one, it is one of the most effective ways of collaborating on a shared project. Hundreds of companies and hundreds of thousands of workers use Git and services like GitHub to work together on massive projects. The way collaboration works would conceptually look like:

%%{init:{'theme':'forest', 'flowchart':{'nodeSpacing': 20, 'rankSpacing':30}}}%%
graph LR;
    yours(Your local) -->|Push| github(GitHub)
    github -->|Pull| yours
    others(Collaborator's<br>local) -->|Push| github
    github -->|Pull| others
Figure 9.2: Schematic showing a local repository, GitHub’s remote repository, and a collaborator’s repository.

This approach to collaborating makes it much easier to contribute directly (not through emails) to projects and to more easily help others out with issues.