gitcreds for package authors

Introduction

If you have a package that queries the GitHub API, or uses git with remote git repositories, then most likely you need to let your users specify their GitHub or git credentials. There are several benefits of using gitcreds to do this:

• (Re)use the same credentials as command line git, R and the RStudio IDE., etc. Users can set their GitHub token once and use it everywhere.

• Users can use the same credentials for multiple R packages.

• gitcreds has a cache that makes credential lookup very fast.

• Typically more secure than storing passwords and tokens in .Renviron files.

• gitcreds supports multiple users and multiple hosts.

• If git or credential helpers are not available, e.g. typically on a Linux server, then gitcreds can still use environment variables, and it still supports multiple users and hosts.

The simple API

The simplest way to use gitcreds is to call gitcreds_get() from your package to query credentials, possibly with a custom URL. For setting new credentials, you can point your users to gitcreds_set().

The low level API

Should you need more flexibility, you can use the gitcreds_approve(), gitcreds_fill() and gitcreds_reject() functions, to add/update, query and remove credentials. We suggest you use the dummy credential helper (see below) for gitcreds_fill(), to avoid git password dialog boxes if a credential is not available.

E.g. the low level API makes it possible to implement an alternative to gitcreds_set() , with a different user interface, or a version that also works in non-interactive sessions.

gitcreds_fill(list(url="https://impossible.com"))
#> [1] "protocol=dummy"     "host=dummy"
#> [3] "username=dummy"     "password=dummy get"

Testing

If your package uses gitcreds, either directly, or through another package, then you might want to test your package for the the various possible states of the user’s git installation and credential store. gitcreds has some facilities to help you with this.

If you want to test your package for a specific output from gitcreds, you can temporarily set the environment variable that gitcreds uses as a cache to the desired value. Use the gitcreds_cache_envvar() function to see which environment variable you need to set for a url:

gitcreds::gitcreds_cache_envvar("https://github.com")

## [1] "GITHUB_PAT_GITHUB_COM"

It is easiest to use the withr package to temporarily change this environment variable in a test case:

library(testthat)
test_that("bad credentials from git", {
  withr::local_envvar(c(GITHUB_PAT_GITHUB_COM = "bad"))
  # Test code that calls gitcreds_get(), potentially downstream.
  # gitcreds_get() will return `bad` as the password.
  # Illustration:
  expect_equal(
    gitcreds::gitcreds_get("https://github.com")$password,
    "bad"
  )
})

## Test passed 🥇

If you want gitcreds to return a specific credential record, then you can specify the fields of the record in the environment variable, separated by colons. For example:

library(testthat)
test_that("another GitHub user", {
  cred <- paste0(
    "protocol:https:",
    "host:github.com:",
    "username:user1:",
    "password:secret"
  )
  withr::local_envvar(c(GITHUB_PAT_GITHUB_COM = cred))
  # Your test code comes here. This is just an illustration:
  print(gitcreds::gitcreds_get())
  expect_equal(gitcreds::gitcreds_get()$username, "user1")
})

## <gitcreds>
##   protocol: https
##   host    : github.com
##   username: user1
##   password: <-- hidden -->
## Test passed 🌈

If you want gitcreds to fail for a specific host, set the corresponding environment variable to "FAIL":

library(testthat)
test_that("no credentials from git", {
  withr::local_envvar(c(GITHUB_PAT_GITHUB_COM = "FAIL"))
  # The test code that calls gitcreds_get() comes here.
  # It will fail with error "gitcreds_no_credentials"
  expect_error(
    gitcreds::gitcreds_get("https://github.com"),
    class = "gitcreds_no_credentials"
  )
})

## Test passed 😸

If you want gitcreds to fail with a specific error, then include the error class after a "FAIL:" prefix, in the environment variable. See the list of possible error classes above. For example:

library(testthat)
test_that("no git installation", {
  withr::local_envvar(c(
    GITHUB_PAT_GITHUB_COM = "FAIL:gitcreds_nogit_error"
  ))
  # Test code that calls gitcreds_get() comes here.
  # Illustration:
  expect_error(
    gitcreds::gitcreds_get("https://github.com"),
    class = "gitcreds_nogit_error"
  )
})

## Test passed 🎊

It is not currently possible to simulate the additional data in the error object, e.g. the standard output of a failed git command. If you need this for a test case, then your test case can call gitcreds_get() directly and you can use the mockery package to make gitcreds fail with the desired error object.