Personal Access Token (PAT)

Personal access tokens (PATs) are an alternative to using passwords for authentication to GitHub when using the GitHub application programming interface (API) or the command line. Personal access tokens are intended to access GitHub resources on your behalf and should never be shared with anyone else.

Generating a PAT

Generating a PAT from within GitHub is relatively straightforward; there are two different ways shown below to access the settings. Once upon a time, PATs never expired, but now for security reasons there are options to have them expire after a set period of time, which you can set.

PAT via GitHub

You can navigate directly to the tokens page in GitHub via https://github.com/settings/tokens.

Alternatively, you can click through the following sequences from your profile page on GitHub.

Task: Click on your profile pic (or default avatar) and select Settings.

Task: Scroll down to the bottom of the lefthand menu and select <> Developer settings.

Task: Select Tokens (classic) from the lefthand menu.

Task: Click on the Generate new token dropdown menu and select Generate new token (classic).

Note: You will likely be prompted for your GitHub password. If so, enter into the box and click the green Submit button.

Task: In the Note field, give your new token an informative title that indicates its intended use.

Task: From the Expiration dropdown menu, select “60 days”, which will be long enough to carry you through the quarter.

Task: Scroll down to the Select scopes section and check the following boxes:

repo
workflow
gist
notifications

Tip: You can read more about scopes and their definitions here.

Task: Scroll down further and check the following boxes:

user
delete_repo
project

Task: When finished, click the green Generate token button.

Note: There are 2 important things here:

Your PAT is just like a password. DO NOT share it with anyone (the example below has much of the PAT grayed out);
Make sure to copy & paste your PAT elsewhere before navigating away from this page.

Task: Click on the blue double-boxes to copy your PAT to the clipboard.

Task: Jump down to the section on storing your PAT for future use and follow the instructions for doing so.

PAT via `{usethis}`

You can also generate a PAT directly from within R by using the {usethis} package.

Note: If you do not already have the {usethis} package installed, you will need to do so. Copy the code below, paste it into the R console, and run it.

if(!require("usethis")) {
  install.packages("usethis")
}

Task: Use usethis::create_github_token() to open up the new tokens on GitHub.

Input

> usethis::create_github_token()

Note: Executing the above R command will respond with the following message and automatically open a new token page in GitHub specified by the URL.

Output

• Call `gitcreds::gitcreds_set()` to register this token in the local Git credential store
  It is also a great idea to store this token in any password-management software that you use
✔ Opening URL 'https://github.com/settings/tokens/new?scopes=repo,user,gist,workflow&description=DESCRIBE THE TOKEN\'S USE CASE'

Task: In the Note field, give your new token an informative title that indicates its intended use.

Task: From the Expiration dropdown menu, select “60 days”, which will be long enough to carry you through the quarter.

Note: The create_github_token() command will auto-select the following scopes:

repo
workflow
gist
user

Task: Scroll down through the Select scopes section and check these additional boxes:

notifications
delete_repo
project

Tip: You can read more about scopes and their definitions here.

Task: When finished, click the green Generate token button.

Note: There are 2 important things here:

Your PAT is just like a password. DO NOT share it with anyone (the example below has much of the PAT grayed out);
Make sure to copy & paste your PAT elsewhere before navigating away from this page.

Task: Click on the blue double-boxes to copy your PAT to the clipboard.

Task: Proceed to the next section and store your PAT for future use.

Store your PAT

Now that you’ve generated a PAT and have copied it to the clipboard, you need to store it for later use when interacting with GitHub via RStudio or the command line.

If you use a third-party password manager (e.g., 1Password), you might want to add your new PAT to the entry for GitHub, where presumably you’ve already stored your username and password when you created your account.

Note: If you misplace your PAT or it doesn’t seem to be working, go ahead and generate a new one.

Tip: If you set an expiration date for your PAT (e.g., 60 days), you might want to set a calendar reminder to generate a new one in the future, so as to avoid the potential head-scratching problem of not being able to push commits to GitHub.

Using `{gitcreds}`

The {gitcreds} package was created specifically for reading and writing Git credentials from within R. It will have been installed along with the {usethis} package.

Tip: Before proceeding, make sure you have created a PAT and copied it to the clipboard.

Task: Use gitcreds::gitcreds_set() to store your PAT. At the prompt, paste your newly created PAT and press ‘return’ (‘enter’) when you are ready.

Input

> gitcreds::gitcreds_set()

Note: The pasted PAT in the example below is ghp_ followed by a string of x’s; your PAT will look different.

Output

? Enter password or token: ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
-> Adding new credentials...
-> Removing credentials from cache...
-> Done.

Note: If you already have a stored PAT, gitcreds::gitcreds_set() will respond with the following information. [your-user-name] will be your GitHub username.

-> Your current credentials for 'https://github.com':
  protocol: https
  host    : github.com
  username: [your-user-name]
  password: <-- hidden -->

-> What would you like to do? 

1: Keep these credentials
2: Replace these credentials
3: See the password / token

Selection: 2
-> Removing current credentials...
? Enter new password or token: ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
-> Adding new credentials...
-> Removing credentials from cache...
-> Done.

Tip: If you have reason to believe your PAT was compromised or it’s simply expired, first create a new one using the steps in this guide, and then select option 2: Replace these credentials when calling gitcreds::gitcreds_set().

Tip: You can check that you’ve stored a credential with gitcreds::gitcreds_get().

Creating a Personal Access Token (PAT)