RStudio Workbench Setup

Step 1: Create a GitHub Account

  1. If you have not yet, go to https://github.com and follow the instructions there to create a free GitHub account. Choose a professional username (see these tips).

  2. Add your GitHub username to the Excel file linked on Lecture 1.

  3. We’ll use your username to invite you to our GitHub Course Organization, which is required to access and submit homework assignments. You’ll receive an invitation email from GitHub — make sure to open it and accept the invitation to join the organization.

Step 2: Log into RStudio Workbench

Go to https://macss-r.uchicago.edu/

Login with your UChicago CNetID and password to login; this is the same username/password you use for other UChicago online services. You’re done. You should see a clean RStudio window in your browser.

Note

Only students approved by SSCS can access this server. If you can’t log in, chances are that you have not yet been added to the server. Email me at nardin@uchicago.edu. For network or cVPN issues, contact ITS.

Step 3: Configure Git in RStudio Workbench

To make Git work smoothly in this course, you’ll configure these settings: (3.1) Identify yourself to Git with your name and email, so Git can track your work and (3.2) Set up SSH Authentication, so GitHub knows it’s you

You only need to do this once per machine!

You can also watch a video walkthrough of the setup process.

3.1 Identify yourself to Git

To track your work and link changes to you, Git needs to know your name and email address.

Go to the Console tab in RStudio and run the code below, replacing name and email with your own:

  • your name can be your GitHub username or your actual first and last name
  • your email must be the same email you used to sign up for GitHub when you created an account
library(usethis)
usethis::use_git_config(user.name = "Your Name", user.email = "your@email.com")

To confirm it worked (e.g., that Git got your credentials), go to Tools > Shell and run the following command in the shell/terminal tab that opens up:

git config --global --list

If you see your name and email, you’re all set. If something looks off—like a typo in your name or you used the wrong email (not the one linked to your GitHub account)—just re-run the R code with the correct information. It will overwrite the previous settings.

3.2 Set Up SSH Authentication

What is this?

Now Git knows your name and email. But to send your work from Git (on your computer – in our case, Workbench) to GitHub (online), you need to prove to GitHub that’s really you — this is called authentication.

When you log into GitHub in your browser, you use your username and password. But Git uses a different method for authentication: either SSH keys or HTTPS with a personal access token. Both options allow Git to connect to GitHub securely, so you can push and pull changes without entering your password each time.

Since we are using the RStudio Workbench for the class, you will need to use SSH keys to authenticate. The server that host our Workbench does not have the ability to cache your personal access token for HTTPS.

The Secure Shell Protocol (SSH) is a secure way to prove your identity when connecting to GitHub. Unlike passwords, which can be vulnerable to brute-force attacks, SSH keys are much harder to crack.

When you generate an SSH key pair, you get two long strings of characters:

  • a public key, which you upload to GitHub
  • a private key, which stays safely on your computer (or in RStudio Workbench)

When you try to connect to GitHub, Git uses your private key to unlock the connection. If it matches the public key on GitHub, you’re authenticated!

Note that on GitHub, the URL for SSH looks like git@github.com:<OWNER>/<REPO>.git (make sure you use this SSH URL to create a project or clone a repository. If you accidentally use the HTTPS version, the operation will not work).

What you need to do to

You need to create and store an SSH key pair, by running the following code in your R Console:

credentials::ssh_setup_github()

You’ll be guided through a few steps:

  • It should say “No SSH key found. Generate one now?” → Type Yes
  • A long string of characters will appear in the Console, that’s your public SSH key
  • You will be asked to open a browser → Type Yes
  • Before or after opening a new browser, copy the entire SSH key (including the ssh-rsa or ssh-ed25519 at the beginning) from your Console

Once you are on the GitHub page:

  • Paste your entire SSH key into the GitHub page that opened in your new browser (you can do this only if you registered a GitHub account, see step 1 above)
  • Under “Title”, give the key an informative name, something like csp-workbench-summer25 or another label to record the course and computer
  • Leave “Key type” set to Authentication Key
  • Click the green “Add SSH key” button
  • If prompted, complete GitHub’s security steps (e.g., enter a verification code or password or anything else asked)

You should now see your key listed in your GitHub account!

To confirm it worked, go back R, then to Tools > Shell and run the following command in the shell/terminal tab that opens up:

ls -l ~/.ssh

You should see two lines showing the keys you just created: id_rsa is your private SSH key (keep it secure and do not share it), your id_rsa.pub is your public SSH key (the one you put on GitHub).

If you see more than these two files, it likely means you’ve set up extra SSH keys, which we want to avoid as it might create problems. Please contact us — we’ll help you reset and start fresh!

What’s next?

If you completed this part successfully, you are ready to test your setup — go to the Git within RStudio Tutorial page and follow the instructions!