api_token: Return the local user's GitHub Personal Access Token (PAT)

In coatless/rest: 'REST' 'API'

Description

You can read more about PATs here: https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/ and you can access your PATs here (if logged in to GitHub): https://github.com/settings/tokens.

Usage

api_token(api_url = NULL)

Arguments

api_url

Github API url. Defaults to GITHUB_API_URL environment variable if set, otherwise https://api.github.com.

Details

Set the GITHUB_PAT environment variable to avoid having to include your PAT in the code. If you work with multiple GitHub deployments, e.g. via GitHub Enterprise, then read 'PATs for GitHub Enterprise' below.

If you want a more secure solution than putting authentication tokens into environment variables, read 'Storing PATs in the system keyring' below.

Value

A string, with the token, or a zero length string scalar, if no token is available.

PATs for GitHub Enterprise

gh lets you use different PATs for different GitHub API URLs, by looking for the PAT in an URL specific environment variable first. It uses slugify_url() to compute a suffix from the API URL, by extracting the host name and removing the protocol and the path from it, and replacing special characters with underscores. This suffix is added to GITHUB_PAT_ then. For example for the default API URL: https://api.github.com, the GITHUB_PAT_API_GITHUB_COM environment variable is consulted first.

You can set the default API URL via the GITHUB_API_URL environment variable.

If the API URL specific environment variable is not set, then gh falls back to GITHUB_PAT and then to ‘GITHUB_TOKEN’.

Storing PATs in the system keyring

gh supports storing your PAT in the system keyring, on Windows, macOS and Linux, using the keyring package. To turn on keyring support, you need to set the rest_KEYRING environment variables to true, in your .Renviron file or profile.

If keyring support is turned on, then for each PAT environment variable, gh first checks whether the key with that value is set in the system keyring, and if yes, it will use its value as the PAT. I.e. without a custom GITHUB_API_URL variable, it checks the GITHUB_PAT_API_GITHUB_COM key first, then the env var with the same name, then the GITHUB_PAT key, etc. Such a check looks like this:

keyring::key_get("GITHUB_PAT_API_GITHUB_COM")

and it uses the default keyring backend and the default keyring within that backend. See keyring::default_backend() for details and changing these defaults.

If the selected keyring is locked, and the session is interactive, then gh will try to unlock it. If the keyring is locked, and the session is not interactive, then gh will not use the keyring. Note that some keyring backends cannot be locked (e.g. the one that uses environment variables).

On some OSes, e.g. typically on macOS, you need to allow R to access the system keyring. You can allow this separately for each access, or for all future accesses, until you update or re-install R. You typically need to give access to each R GUI (e.g. RStudio) and the command line R program separately.

To store your PAT on the keyring run

keyring::key_set("GITHUB_PAT")

See Also

slugify_url() for computing the environment variables that gh uses to search for API URL specific PATs.

coatless/rest documentation built on May 27, 2020, 12:03 a.m.