B GitHub Personal Access Tokens

If you Git push or pull via the command line, you can avoid the constant authentication challenge by caching your username and password for HTTPS access or by setting up SSH keys. This includes any Git operations done by RStudio on your behalf.

But for some operations you must call the GitHub API (Application Programming Interface). And this requires that you authenticate yourself in a different way.

B.1 GitHub API

The first reason most people need GitHub API access is because they want to use the devtools package. It is popular for the devtools::install_github() function to install directly from GitHub. This is in contrast to installing a package from CRAN via install.packages().

Why install from GitHub instead of CRAN?

  • The package is developed on GitHub and you prefer the development version because it has some features or bug fixes not yet on CRAN.
  • You contribute to or use R packages that are in private repositories on GitHub (or GitHub Enterprise). CRAN is not an option.

Other reasons to call the GitHub API include doing almost anything you might do in the browser, especially if you need to do it on a grand scale, i.e., create repositories or users or fetch data. I recommend the gh package for this. Which you must install from GitHub!

B.2 How do you authenticate yourself?

With access via API, what plays the role of the HTTPS username/password or SSH keys? For the GitHub API, we use a personal access token (PAT), which is a convention followed by many other APIs.

You will need to:

  • Obtain a PAT. This is done in the browser.
  • Store it so packages like devtools can find it and use it on your behalf. The path of least resistance is to define it in your .Renviron file as the environment variable named GITHUB_PAT.

B.3 Step-by-step

Login to your GitHub account. Go to https://github.com/settings/tokens.

“Generate new token”. Give it a nickname that reminds you of the intended purpose, e.g., “devtools”.

Pick scopes that confer the privileges you need. When in doubt, check the repo scope, which is required for typical devtools operations. There used to be a set of default scopes, but that no longer appears to be true.

After you click “Generate token”, the token will be displayed. It’s a string of 40 random letters and digits. This is the last time you will see it SO COPY IT TO THE CLIPBOARD. Leave this window open until you’re done. If you somehow goof this up, just generate a new one and try again.

Put your PAT in your .Renviron file. Have a line that looks like this:

GITHUB_PAT=8c70fd8419398999c9ac5bacf3192882193cadf2

but with your PAT instead of mine. Don’t worry, I’ve revoked this one! This file should live in your home directory. Not sure what that is? In R, do:

normalizePath("~/")

If you have no idea how to do any of this, here’s one way from R:

cat("GITHUB_PAT=8c70fd8419398999c9ac5bacf3192882193cadf2\n",
    file = file.path(normalizePath("~/"), ".Renviron"), append = TRUE)

but with your PAT instead of mine.

Here’s another way with RStudio (or other text editor): Do File > New File > Text file. Create a line like this:

GITHUB_PAT=8c70fd8419398999c9ac5bacf3192882193cadf2

Put a line break at the end! If you’re using an editor that shows line numbers, there should be two lines, where the second one is empty.

Save in your home directory with the filename .Renviron. If questioned, YES you do want to use a filename that begins with a dot .. Note that, by default, dotfiles are hidden in RStudio, but .Renviron should always be visible and therefore easy to edit in the future.

Restart R (Session > Restart R in the RStudio menu bar), as environment variables are loaded from .Renviron only at the start of an R session. Check that the PAT is now available like so:

Sys.getenv("GITHUB_PAT")

You should see your PAT print to screen.

Now commands you run from the devtools package, which consults GITHUB_PAT by default, will be able to access private GitHub repositories to which you have access, and you can install them with devtools::install_github('username/reponame').

B.4 A note about security

Many R packages that access web services, such as those maintained by rOpenSci, give the option of storing API “tokens” or “keys” as environment variables in your .Renviron file. These tokens and this file, should never be committed to GitHub, stored in Dropbox, or on any other online service. They should not appear in your code or code comments. This is one reason why this file is stored outside your project folder. These tokens can be used to access your accounts and wreak all kinds of havoc. If you mistakenly share your tokens, log into the relevant site via the browser, revoke the compromised token, and generate a new one.

B.5 Why .Renviron instead of bash config?

FAQ: Why define this environment variable via .Renviron instead of in .bash_profile or .bashrc?*

Because there are many combinations of OS and ways of running R where the .Renviron approach “just works” and the bash stuff does not. When R is a child process of, say, Emacs or RStudio, you can’t always count on environment variables being passed to R. Put them in an R-specific start-up file and save yourself some grief.