added section on personal access tokens. Closes #306

Author: ttimbers

img/generate-pat_01.png

@@ -468,6 +468,7 @@ version control: you won't be able to see, interpret, or find changes in the his
 of any of the actual content of your project!
 
 ## Working with local repositories using Jupyter {#local-repo-jupyter}
+
 Although there are several ways to create and edit files on GitHub, they are
 not quite powerful enough for efficiently creating and editing complex files,
 or files that need to be executed to assess whether they work (e.g., files
@@ -477,10 +478,70 @@ remote repository that was created on GitHub to a local coding environment.  Thi
 can be done by creating and working in a local copy of the repository.
 In this chapter, we focus on interacting with Git via Jupyter using
 the Jupyter Git extension. The Jupyter Git \index{git!Jupyter extension} extension
-can be run via Jupyter on your local computer, or on a JupyterHub server. 
+can be run by Jupyter on your local computer, or on a JupyterHub server. 
 *Note: we recommend reading Chapter \@ref(getting-started-with-jupyter)* 
 *to learn how to use Jupyter before reading this chapter.*
 
+### Generating a GitHub personal access token
+
+To send and retrieve work between your local computer 
+and the remote version control repository on GitHub,
+you will frequently need to perform authentication 
+to prove you have the permission to do this.
+There are several methods to do this, 
+but for beginners we recommend using the HTTPS method 
+because it is easier to do and requires less setup.
+In order to use the HTTPS method, 
+GitHub requires the use of a personal access token 
+(PAT)\index{git!personal access token} 
+in place of a password because it is more secure.
+To generate a personal access token, 
+go to the Personal access tokens section of the Developer Settings page 
+(accessed via the Settings menu).
+This is accessible via: 
+[https://github.com/settings/tokens](https://github.com/settings/tokens).
+Once there, click "Generate new token" (Figure \@ref(fig:generate-pat-01)).
+Note that you may be asked to re-authenticate with your username 
+and password to proceed.
+
+(ref:generate-pat-01) The "Generate new token" button used to initiate the creation of a new personal access token. It is found on the Personal access tokens section of the Developer Settings page (accessed via the Settings menu).
+
+```{r generate-pat-01, fig.cap = '(ref:generate-pat-01)', fig.retina = 2, out.width="100%"}
+image_read("img/generate-pat_01.png")
+```
+
+Next you will be asked to add a note for your personal access token 
+(this should be a descriptor of what you are using it for) 
+and then select the scope of permission given to the token. 
+We recommend selecting only the "repo" to err on the side of higher security. 
+To generate the token, scroll to the bottom of that page 
+and click the green "Generate token" button (Figure \@ref(fig:generate-pat-02)).
+
+(ref:generate-pat-02) Webpage for creating a new personal access token.
+
+```{r generate-pat-02, fig.cap = '(ref:generate-pat-02)', fig.retina = 2, out.width="100%"}
+image_read("img/generate-pat_02.png")
+```
+
+Finally, you will be taken to a page where you will be able to see 
+and copy the personal access token you just generated. 
+You will only be able to see this once, 
+so make sure you store this in a safe place 
+that just you can access when you need to use it in the future 
+for authentication (Figure \@ref(fig:generate-pat-03)).
+For example, a password manager is an excellent place to securely store this, 
+and other, personal access tokens.
+
+(ref:generate-pat-03) Display of the newly generated personal access token.
+
+```{r generate-pat-03, fig.cap = '(ref:generate-pat-03)', fig.retina = 2, out.width="100%"}
+image_read("img/generate-pat_03.png")
+```
+
+If you want to learn more about GitHub authentication, 
+we link to two excellent sources for this in our additional resources section 
+at the end of this chapter.
+
 ### Cloning a repository using Jupyter 
 
 The first step is to *clone* the \index{git!clone} remote repository on GitHub to create a local repository,
@@ -865,7 +926,8 @@ Now that you've picked up the basics of version control with Git and GitHub,
 you can expand your knowledge through the resources listed below:
 
 - GitHub's [guides website](https://guides.github.com/) and [YouTube channel](https://www.youtube.com/githubguides),
-and [Happy Git](https://happygitwithr.com/) are great resources to take the next steps in learning about Git and GitHub.
+and [*Happy Git with R*](https://happygitwithr.com/) are great resources to take the next steps in learning about Git and GitHub.
 - [Good enough practices in scientific computing](https://journals.plos.org/ploscompbiol/article?id=10.1371/journal.pcbi.1005510#sec014) [-@wilson2014best] provides more advice on useful workflows and "good enough" practices in data analysis projects.
 - In addition to [GitHub](https://github.com), there are other popular Git repository hosting services such as [GitLab](https://gitlab.com) and  [BitBucket](https://bitbucket.org). Comparing all of these options is beyond the scope of this book, and until you become a more advanced user you are perfectly fine to just stick with GitHub. Just be aware that you have options!
-
+- If you need additional help generating and using a personal access token with GitHub,
+[GitHub's documentation on creating a personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) and the *Happy Git with R* [Cache credentials for HTTPS](https://happygitwithr.com/credential-caching.html) chapter are excellent additional resources for this.