use_github() takes a local project and:
Checks that the initial state is good to go:
Project is already a Git repo
Current branch is
No uncommitted changes
Creates an associated repo on GitHub
Adds that GitHub repo to your local repo as the
Offers to commit changes, e.g. the addition of GitHub links to the URL and BugReports fields of DESCRIPTION
Makes an initial push to GitHub
origin/master to be the upstream branch of the local
See the Authentication section below for general setup that is necessary for all of this to work.
use_github( organisation = NULL, private = FALSE, protocol = git_protocol(), auth_token = github_token(), host = NULL, credentials = deprecated() )
If supplied, the repo will be created under this
organisation, instead of the account of the user associated with the
Optional. Should be "ssh" or "https", if specified. Defaults
to the option
GitHub personal access token (PAT).
GitHub API host to use. Override with the endpoint-root for your GitHub enterprise instance, for example, "https://github.hostname.com/api/v3".
: No longer consulted now that usethis uses the gert package for Git operations, instead of git2r. Note that gert relies on the credentials package for auth.
This function potentially interacts with GitHub in two different ways:
via the GitHub REST API
as a conventional Git remote
Therefore two types of auth happen.
To create a new repo on GitHub, we must call the GitHub REST API, i.e. this isn't one of the standard remote Git operations. Therefore you must make a GitHub personal access token (PAT) available. There are two ways to do this, in order of preference:
Configure your token as the
GITHUB_PAT env var. Then it can be used by
many packages and functions, without any effort on your part. If you don't
have a token yet or you haven't configured it as an env var, see
Provide the token directly via the
When we clone or pull from GitHub or push to it, depending on the protocol (HTTPS vs. SSH) and the privacy of the repo, we may also need regular Git credentials, just like we'd need with command line Git.
We highly recommend using the HTTPS protocol, unless you have a specific
preference for SSH. If you are an "HTTPS person", your GitHub PAT (see above)
can also be used to authorize standard Git remote operations. Once you've
configured your PAT, your setup is complete! See
use_git_protocol() for how
to tell usethis about your preference for HTTPS (or SSH) by setting an
But what about SSH? usethis uses the gert package for Git operations and gert, in turn, relies on the credentials package for auth:
In usethis v1.7.0, we switched from git2r to gert + credentials. The main motivation is to provide a smoother user experience by discovering and using the same credentials as command line Git (and, therefore, the same as RStudio). The credentials package should automatically discover your SSH keys. This works so well that we have removed all credential-handling workarounds from usethis. If you have credential problems, focus your troubleshooting on getting the credentials package to find your SSH keys. Its introductory vignette is a good place to start.