Package 'credentials'

Retrieve and store git HTTPS credentials

Description

Low-level wrappers for the git-credential command line tool. Try the user-friendly git_credential_ask and git_credential_update functions first.

Usage

credential_fill(cred, verbose = TRUE)

credential_approve(cred, verbose = TRUE)

credential_reject(cred, verbose = TRUE)

Arguments

cred	named list with at least fields protocol and host and optionally also path, username ,password.
verbose	emit some useful output about what is happening

Details

The credential_fill function looks up credentials for a given host, and if none exists it will attempt to prompt the user for new credentials. Upon success it returns a list with the same protocol and host fields as the cred input, and additional username and password fields.

After you have tried to authenticate the provided credentials, you can report back if the credentials were valid or not. Call credential_approve and credential_reject with the cred that was returned by credential_fill in order to validate or invalidate a credential from the store.

Because git credential interacts with the system password manager, the appearance of the prompts vary by OS and R frontend. Note that credential_fill should only be used interactively, because it may require the user to enter credentials or unlock the system keychain. On the other hand credential_approve and credential_reject are non-interactive and could be used to save or delete credentials in a scripted program. However note that some credential helpers (e.g. on Windows) have additional security restrictions that limit use of credential_approve and credential_reject to credentials that were actually entered by the user via credential_fill. Here it is not possible at all to update the credential store without user interaction.

Examples

# Insert example cred
example <- list(protocol = "https", host = "example.org",
  username = "test", password = "secret")
credential_approve(example)

# Retrieve it from the store
cred <- credential_fill(list(protocol = "https", host = "example.org", path = "/foo"))
print(cred)

# Delete it
credential_reject(cred)

---

Credential Helpers

Description

Git supports several back-end stores for HTTPS credentials called helpers. Default helpers include cache and store, see the git-credentials manual page for details.

Usage

credential_helper_list()

credential_helper_get(global = FALSE)

credential_helper_set(helper, global = FALSE)

Arguments

global	if FALSE the setting is done per git repository, if TRUE it is in your global user git configuration.
helper	string with one of the supported helpers from credential_helper_list

---

Load and store git HTTPS credentials

Description

This requires you have the git command line program installed.The git_credential_ask function looks up a suitable username/password from the git-credential store. If none are available it will prompt the user for credentials which may be saved the store. On subsequent calls for the same URL, the function will then return the stored credentials without prompting the user.

Usage

git_credential_ask(url = "https://github.com", save = TRUE, verbose = TRUE)

git_credential_update(url = "https://github.com", verbose = TRUE)

git_credential_forget(url = "https://github.com", verbose = TRUE)

Arguments

url	target url, possibly including username or path
save	in case the user is prompted for credentials, attempt to remember them.
verbose	print errors from ⁠git credential⁠ to stdout

Details

The appearance and security policy of the credential store depends on your version of git, your operating system, your R frontend and which credential_helper is used. On Windows and MacOS the credentials are stored in the system password manager by default.

It should be assumed that reading credentials always involves user interaction. The user may be asked to unlock the system keychain or enter new credentials. In reality, user interaction is usually only required on the first authentication attempt, but the security policy of most credential helpers prevent you from programmatically testing if the credentials are already unlocked.

See Also

Other credentials: ssh_credentials

---

Set your Github Personal Access Token

Description

Populates the GITHUB_PAT environment variable using the git_credential manager, which git itself uses for storing passwords. The credential manager returns stored credentials if available, and securely prompt the user for credentials when needed.

Usage

set_github_pat(force_new = FALSE, validate = interactive(), verbose = validate)

Arguments

force_new	forget existing pat, always ask for new one.
validate	checks with the github API that this token works. Defaults to TRUE only in an interactive R session (not when running e.g. CMD check).
verbose	prints a message showing the credential helper and PAT owner.

Details

Packages that require a GITHUB_PAT can call this function to automatically set the GITHUB_PAT when needed. Users may call this function in their .Rprofile script to automatically set GITHUB_PAT for each R session without hardcoding any tokens on disk in plain-text.

Value

Returns TRUE if a valid GITHUB_PAT was set, and FALSE if not.

---

Managing Your SSH Key

Description

Utility functions to find or generate your SSH key for use with git remotes or other ssh servers.

Usage

ssh_key_info(host = NULL, auto_keygen = NA)

ssh_keygen(file = ssh_home("id_ecdsa"))

ssh_setup_github()

ssh_home(file = NULL)

ssh_agent_add(file = NULL)

ssh_update_passphrase(file = ssh_home("id_rsa"))

ssh_read_key(file = ssh_home("id_rsa"), password = askpass)

Arguments

host	target host (only matters if you have configured specific keys per host)
auto_keygen	if TRUE automatically generates a key if none exists yet. Default NA is to prompt the user what to.
file	destination path of the private key. For the public key, .pub is appended to the filename.
password	a passphrase or callback function

Details

Use ssh_key_info() to find the appropriate key file on your system to connect with a given target host. In most cases this will simply be ssh_home('id_rsa') unless you have configured ssh to use specific keys for specific hosts.

To use your key to authenticate with GitHub, copy the pubkey from ssh_key_info() to your profile: https://github.com/settings/ssh/new.

If this is the first time you use ssh, ssh_keygen can help generate a key and save it in the default location. This will also automatically opens the above Github page in your browser where you can add the key to your profile.

ssh_read_key reads a private key and caches the result (in memory) for the duration of the R session. This prevents having to enter the key passphrase many times. Only use this if ssh-agent is not available (i.e. Windows)

See Also

Other credentials: http_credentials

---