A personal access token (PAT) is needed for certain tasks usethis does via the GitHub API, such as creating a repository, a fork, or a pull request. If you use HTTPS remotes, your PAT is also used when interacting with GitHub as a conventional Git remote. These functions help you get and manage your PAT:

  • create_github_token() opens a browser window to the GitHub form to generate a PAT. It then offers advice on storing your PAT, which also appears below.

  • credentials::set_github_pat() helps you register your PAT with the Git credential manager used by your operating system. It can also use that PAT to set the GITHUB_PAT env var in an R session.

  • github_token() retrieves a stored PAT by consulting, in this order:

    • GITHUB_PAT environment variable

    • GITHUB_TOKEN environment variable

    • the empty string ""

create_github_token() has previously gone by some other names: browse_github_token() and browse_github_pat().

create_github_token(
  scopes = c("repo", "gist", "user:email"),
  description = "R:GITHUB_PAT",
  host = "https://github.com"
)

github_token()

Arguments

scopes

Character vector of token scopes, pre-selected in the web form. Final choices are made in the GitHub form. Read more about GitHub API scopes at https://developer.github.com/apps/building-oauth-apps/scopes-for-oauth-apps/.

description

Short description or nickname for the token. It helps you distinguish various tokens on GitHub.

host

GitHub API host to use. Override with the endpoint-root for your GitHub enterprise instance, for example, "https://github.hostname.com/api/v3".

Value

github_token() returns a string, a GitHub PAT or "".

Details

Sign up for a free GitHub.com account and sign in. Call create_github_token(). Verify the scopes and click "Generate token". Copy the token right away! A common approach is to store in .Renviron as the GITHUB_PAT environment variable. edit_r_environ() opens this file for editing.

A more secure alternative is to call credentials::set_github_pat() which prompts you for your PAT and stores it with the Git credential manager used by your operating system. Once stored, a call to credentials::set_github_pat() retrieves this value and assigns it to the GITHUB_PAT environment variable. This would be a great thing to put in a startup file to make your PAT available in all R sessions. Remember edit_r_profile() is handy for editing your .Rprofile. The advantage of this approach is that your PAT is never stored in regular file, as plain text.

See also

gh::gh_whoami() for information on an existing token and credentials::set_github_pat() for a secure way to store and retrieve your PAT.

Examples

if (FALSE) { create_github_token() # COPY THE PAT!!! # almost certainly to be followed by ... edit_r_environ() # which helps you store the PAT as an env var # or a call to credentials::set_github_pat() # which helps you store the PAT in the git credential store } # for safety's sake, just reveal first 4 characters substr(github_token(), 1, 4)
#> [1] "v1.2"