Connecting Posit Workbench (RStudio) to GitHub with HTTPS

If you're an RStudio user using Posit Workbench and want to use GitHub for source control (you should), this is the guide for you.

There are two ways to connect: SSH and HTTPS. Named for the different protocols they use under the hood. If your company IT department recommend one over the other, you should follow their instructions on how. If they don't, or those instructions don't help, read on.

Whilst SSH is considered the gold standard way to connect, it is more finickity to set up. For most users - especially newer ones - it is easier to set up an HTTPS connection. Which is what we are going to walk through in this post.

The steps described are for those using RStudio as part of Posit Workbench, but the steps are almost identical if you are using RStudio Server or a locally installed version of RStudio.

The following steps will get you up and running with an HTTPS connection between Posit Workbench (RStudio) and GitHub.

1. Login to GitHub and Posit Workbench
2. Create a Personal Access Token (PAT) on GitHub
3. Register your GitHub PAT in Posit Workbench / RStudio
4. Test your GitHub connection

Specific step instructions are presented as bullet points under each section. You should work through them in the order given.

Step 1: Login to GitHub and Posit Workbench

Before you start, you'll need a few things in place.

• A GitHub account: open in a browser window and log in.
• An RStudio Workbench account: log in and open RStudio in a browser window.
• Access to an R project repo on GitHub (to test the connection - but if you don't have one, you can create an empty repo directly on GitHub when you come to testing).

To connect to GitHub using HTTPS you will need to set up a Personal Access Token (PAT) from GitHub, then configure RStudio to use this.

Think of a PAT as a long and complex password that is generated for you. One that is used for a single purpose and that you will only have to enter once, when you set up the connection.

Once you have registered your GitHub-generated PAT in RStudio, it will remember these credentials between sessions. Meaning you should only need to repeat these steps if / when you change your PAT code. (Which we recommend you do at least once per year.)

Step 2: Create your Personal Access Token (PAT) on GitHub

Login to your GitHub account and navigate to Developer Settings

• Login to GitHub and navigate to Settings > Developer settings. 
  
  If you are logged into GitHub, you can find this by clicking on your profile image (top right of screen) and selecting "Settings" from the menu which appears. Followed by "Developer settings" from the menu on the next page.
  
  Alternatively, just click the link above to go directly to the page's URL:
  https://github.com/settings/apps
• Expand the menu on the left-hand side labelled "Personal access tokens".
• Click on "Tokens (classic)".

Generate a new token

You will be taken to a page which lists any personal access tokens you have previously created, with options to delete existing tokens or create new ones.

• Click on the drop-down button labelled "Generate new token" on the right-hand side.
• From the expanded options, select "Generate new token (classic)".

At this stage you may be prompted to confirm your access. If so, follow the instructions to do so. The process may vary slightly depending upon what security you have set up on your GitHub account. The screenshot below is as seen by an account with a Security Key used as second factor authentication.

You will then be presented with a form-style page asking for some details for your new Personal Access Token.

• Enter a short description in the Note box (e.g. “RStudio Workbench connection”). 
  
  This is how it will be labelled if you return to the setting pages which lists your GitHub PATs later. You want this to be descriptive enough that future-you can easily tell what it is when they log on in a few months’ time.
• Set an expiration date. 
  
  The drop down gives you options for 7, 30, 60, 90 days, custom or no expiry. It is good practice to set an expiry date, so don’t pick the “no expiry” option. We recommend using "custom" and setting it to last for one year.
• Under Select scopes, select "repo", "workflow" and "user" (as shown in the image below).

• Optional, but highly recommended: set a reminder in your calendar for a few weeks before the PAT is due to expire. (You will need to create a new one then and repeat these steps.)
• Click the green "Generate token" button at the foot of the form.

Copy the generated PAT code

You will be returned to the screen listing all your Personal Access Tokens. The one you've just created and any others you had already.

The PAT you've just created will be first on the list and you will see the actual code: a fairly long garbage-looking set of characters and numbers. This is the only time you will see this token displayed in GitHub. For security reasons, after leaving this page you will not be able to see the token again, only its labelled name listed with an option to delete it.

• Take a temporary copy of the PAT code which has been generated. Clicking the icon to the right of the code will copy it to your clipboard.

We recommend opening the Notepad application in Windows (or the equivalent on MacOS). Paste the code into the Notepad widow, but don't save it to a file. Just keep Notepad open until you complete the remaining steps below – so you can copy the PAT again, if necessary, should you mess up. Once you are set up, close Notepad without saving.

If you want to keep a permanent copy of the PAT code, store it in a secure password manager like LastPass or 1Password. Though there is really no need. You should not re-use this PAT for anything else. If you find yourself needing another PAT code - perhaps for a local RStudio installation on a home PC - you should create a fresh one specific to that purpose.

Do not save your PAT code to a file or write it on a post-it, and don't share it with anyone else.

Step 3: Register your GitHub PAT in Posit Workbench / RStudio

• Switch to your RStudio browser window. 
  
  It doesn’t matter what (if any) project you have open.
• In the R terminal window, install the credentials package:
  
  install.packages("credentials")

• Then run the following command:
  
  credentials::set_github_pat()

• Enter your GitHub login credentials and PAT code when prompted.

Step 4: Test your connection to GitHub

• In GitHub, navigate to the R project repo you want to work with.
  
  If you don't have one, create a new empty GitHub repository for the purpose. You can delete it after.
• Click on the green Code button, select Local > HTTPS and copy the URL (which will start “https://github.com/...”).

• Switch to the RStudio browser window and select File > New Project > Version Control > Git.
• Paste the URL you just copied into the "Repository URL" box. It will auto-populate the "Project directory name". You can change this, but we recommend you don’t. Things can get confusing later if you do.
  
  You can specify the "local" location to store the repo but, again, we recommend you leave this on its default unless you have good reason and know what you’re doing.

• Click Create Project.

If everything has worked, you’ll be launched into a copy of the project in RStudio and should notice a "Git" tab in the top right pane (on the default RStudio layout).

This gives you a point-and-click interface to perform the most common Git actions (e.g. making commits, pulling and pushing to sync with GitHub, creating and switching branches).

• You can also use the Terminal window to run any valid Git command line function. Test it out by running:
  
  git status

You should see something like the image below. If you do, everything is good.

You are now ready to start using Git to manage your R code.

If you're still stuck, book a free 15 minute video help call and we'll help you implement this in practice.