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 the default branch, e.g.
No uncommitted changes
Creates an associated repo on GitHub
Adds that GitHub repo to your local repo as the
Makes an initial push to GitHub
use_github_links(), if the project is an R package
origin/DEFAULT to be the upstream branch of the local
DEFAULT branch, e.g.
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(), host = NULL, auth_token = deprecated(), credentials = deprecated() )
If supplied, the repo will be created under this
organisation, instead of the login associated with the GitHub token
discovered for this
One of "https" or "ssh"
GitHub host to target, passed to the
For a hypothetical GitHub Enterprise instance, either "https://github.acme.com/api/v3" or "https://github.acme.com" is acceptable.
: No longer consulted now
that usethis uses the gert package for Git operations, instead of git2r;
gert relies on the credentials package for auth. The API requests are now
authorized with the token associated with the
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. See
advice on getting and storing your token.
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. Therefore, once you've configured your PAT, your setup is complete!
But what if you prefer the SSH protocol? usethis uses the gert package for Git operations and gert, in turn, relies on the credentials package for auth:
In usethis v2.0.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.