Functions in projmgr that pull information from GitHub (e.g. get_issues) or send information to GitHub (e.g. post_issue) require credentials for authentication. Just like users are asked to provide a username and password when logging in to the GitHub’s website, these credentials identify you, protect your information security, and prevent unauthorized parties from altering your information (among other API-specific purposes.) However, there are many reasons you won’t want to send your username and password through these functions. First of all, it’s inconvenient to type your credentials over and over. More importantly, it’s generally a bad idea to hardcode your password; you might accidentally sharing a script that has your password in it.

An easier and safer approach to authentication is the personal access token (PAT). At a high level, this is a random string of characters GitHub assigns to you and you alone. By saving this in your R environment, projmgr can automatically provide this variable to GitHub instead of your login for better safety and efficiency.

For more information beyond this vignette, check out the relevant section of Jenny Bryan’s Happy Git with R ebook.

Experimenting without a PAT

For basic GET requests on public GitHub repos, a PAT is not strictly neccessay. You can still obtain some information from the GitHub API with no authetitcation; however, you may run into some roadblocks or be allowed fewer total requests per a fixed amount of time (also known as a rate limit).

If you want to try this, simply pass any value into the identifer argument of create_repo_ref() that is not an environment variable on your system. For example, if:

Sys.getenv("XYZ")

returns an empty string, that means it is not in use. Then,

ref <- create_repo_ref("my_username", "my_repo", identifier = "XYZ")

will allow you to proceed without authentication.

Getting a PAT

Getting a PAT from GitHub is easy!

  1. Go to GitHub
  2. Click on your username and/or profile picture
  3. Choose Settings
  4. Choose Developer Settings
  5. In the left sidebar, choose Personal access tokens
  6. Choose Generate new token
  7. Provide a name and description for your token. This doesn’t really matter very much.
  8. Choose Generate token
  9. Copy the token you are given to your clipboard.

Setting your PAT

In RStudio

On you’ve gotten your random character string, setting your PAT in R is easy. Run the following command to open your R environment file:

usethis::edit_r_environ()

This will pop out your .Renviron file. In it you can simply add a new line with:

GITHUB_PAT = 'asj382058235u0sdij0486jj205270d'

with the character string above replaced with the one you received from GitHub (but you do need to keep the quotes!)

Not in RStudio

If you aren’t in RStudio, you will have to locate you .Renviron file yourself to add this line. For more context on the .Renviorn file, please see the relevant section in Colin Gillespie and Robin Lovelace’s Efficient R Programming book.

Using multiple PATs

In some cases, you may need to maintain more than one GitHub PAT on your computer. For example, if your company has GitHub enterprise, you might have separate personal access tokens for both your personal/public GitHub account and your enterprise account. You can do this by following the steps above multiple times and giving your tokens different names.

For example:

GITHUB_PAT = 'asj382058235u0sdij0486jj205270d'
GITHUB_ENT_PAT = 'djghdu830603jfhdktej3n4aj38090dj'

The create_repo_ref() documentation and the Basic Usage vignette describe how to specify the name of the environment variable containing your PAT if it is not one of the defaults.