This manual page is for users of packages that depend on gitcreds
for managing tokens or passwords to GitHub or other git repositories.
If you are a package author and want to import gitcreds for this
vignette("package", package = "gitcreds").
Otherwise please start at 'Basics' below.
1 2 3 4 5 6 7
URL to get, set or delete credentials for. It may contain a user name, which is typically (but not always) used by the credential helpers. It may also contain a path, which is typically (but not always) ignored by the credential helpers.
Whether to try to use the environment variable cache
before turning to git to look up the credentials for
Whether to set the environment variable cache after
receiving the credentials from git. See
gitcreds_get() returns a
gitcreds object, a named list
of strings, the fields returned by the git credential handler.
Typically the fields are
Some credential helpers support path-dependent credentials and also
gitcreds_set() returns nothing.
FALSE if it did not find find any
credentials to delete, and thus it did not call
git credential reject.
Otherwise it returns
gitcreds_get() errors if git is not installed, no credential helpers
are configured or no credentials are found.
gitcreds_set() errors if
git is not installed, or setting the new credentials fails.
gitcreds_delete() errors if git is not installed or the git calls fail.
vignette("package", package = "gitcreds") if you want to handle
gitcreds_list_helpers() returns a character vector,
corresponding to the
credential.helper git configuration key.
Usually it contains a single credential helper, but it is possible to
configure multiple helpers.
gitcreds_get() queries git credentials. It is typically used by package
code that needs to authenticate to GitHub or another git repository.
The end user might call it to checks that credentials are properly set
gitcreds_set() add or updates git credentials in the credential store.
It is typically called by the user, and it only works in interactive
sessions. It always asks for acknowledgement before it overwrites
gitcreds_delete() deletes git credentials from the credential store.
It is typically called by the user, and it only works in interactive
sessions. It always asks for acknowledgement.
gitcreds_list_helpers() lists the active credential helpers.
These functions use the
git credential system command to query and set
git credentials. They need an external git installation. You can
download git from https://git-scm.com/downloads. A recent version, but
at least git 2.9 is suggested.
If you want to avoid installing git, see 'Environment variables' below.
To set up password-less authentication to GitHub:
create a personal access token (PAT). See https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token.
gitcreds_set() and give this token as the password.
gitcreds_get(use_cache = FALSE) to check that the new
PAT is set up. To see the token, you can run
gitcreds_get(use_cache = FALSE)$password.
If you already have a GitHub token, and use the
GITHUB_TOKEN environment variable in your
.Renviron file or
elsewhere, no changes are neccessary. gitcreds will automatically use
However, we still suggest that you add your token to the git credential
gitcreds_set() and remove
GITHUB_PAT from your
.Renviron file. The credential store is more secure than storing
tokens in files.
Because querying the git credential store might not be very fast,
gitcreds_get() caches credentials in environment variables by default.
Credentials for different URLs are stored in different environment
variables. The name of the environment variable is calculated with
To remove the cache, remove this environment variable with
If you want to avoid installing git, or using the credential store for
some reason, you can supply credentials in environment variables, e.g.
.Renviron file. Use
gitcreds_cache_envvar() to query the
environment variable you need to set for a URL:
You can set this environment variable to the token or password itself.
If you also need a user name, then use the
user:password form, i.e.
separate them with a colon. (If your user name or passwrd has
characters, then you need to escape them with a preceding backslash.)
git credential helpers are an extensible, configurable mechanism to store credentials. Different git installations have different credentials helpers. On Windows the default helper stores credentials in the system credential store. On macOS, it stores them in the macOS Keychain. Other helpers cache credentials in a server process or in a file on the file system.
gitcreds only works if a credential helper is configured. For the current git version (2.28.0), this is the case by default on Windows and macOS (for git from HomeBrew), but most Linux distributions do not set up a default credential helper.
You can use
gitcreds_list_helpers() to see the active credential
helper(s) for a repository.
git allows repository specific configuration, via the
config file might specify a different credential helper, a
different user name, etc. This means that
gitcreds_get() etc. will
potentially work differently depending on the current working
directory. This is especially relevant for package code that changes
the working directory temporarily.
Non-GitHub URLs work mostly the same way as GitHub URLs.
gitcreds_set() default to GitHub, so you'll need
to explicitly set their
Some credential helpers, e.g. Git Credential Manager for Windows
manager) and Git Credential Manager Core (
slightly differently for GitHub and non-GitHub URLs, see their
documentation for details.
The various credential helpers support multiple accounts in different ways. Here are our recommendations.
Use the (currently default)
osxkeychain credential helper.
In Keychain Access, remove all your current credentials for the host(s) you are targeting. E.g. for GitHub, search for github.com Internet Passwords.
Then add the credential that you want to use for "generic access". This is the credential that will be used for URLs without user names. The user name for this credential does not matter, but you can choose something descriptive, e.g. "token", or "generic".
Configure git to use this username by default. E.g. if you chose "generic", then run
git config –global crendetial.username generic
Add all the other credentials, with appropriate user names. These are the user names that you need to put in the URLs for the repositories or operations you want to use them for. (GitHub does not actually use the user names if the password is a PAT, but they are used to look up the correct token in the credential store.)
If you only need to manage a single github.com credential, together with
possibly multiple credentials to other hosts (including GitHub
Enterprise hosts), then you can use the default
manager helper, and
get away with the default auto-detected GCM authority setting.
In this case, you can add you github.com credential with an arbitrary user name, and for each other host you can configure a default user name, and/or include user names in the URLs to these hosts. This is how to set a default user name for a host:
git config --global credential.https://example.com.username myusername
If you need to manage multiple github.com credentials, then you can
still use the
manager helper, but you need to change the GCM authority
by setting an option or an environment variable, see
is merged, you won't need to do this. (At least in recent git versions,
that contain a GCM build with the fix.)
This is how to change GCM authority in the config:
git config --global credential.authority Basic
You can also change it only for github.com:
git config --global credential.github.com.authority Basic
Then you can configure a default user name, this will be used for URLs without a user name:
git config --global credential.username generic
Now you can add you credentials, the default one with the "generic" user name, and all the others with their specific user and host names.
It is possible to configure multiple credential helpers. If multiple
helpers are configured for a repository, then
go over them until a credential is found.
gitcreds_set() will set the
new credentials in every configured credential helper.
You can use
gitcreds_list_helpers() to list all configured helpers.
1 2 3 4 5 6
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.