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 below for the authentication 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
Many usethis functions, including those documented here, potentially interact with GitHub in two different ways:
Via the GitHub REST API. Examples: create a repo, a fork, or a pull request.
As a conventional Git remote. Examples: clone, fetch, or push.
Therefore two types of auth can happen and your credentials must be discoverable. Which credentials do we mean?
A GitHub personal access token (PAT) must be discoverable by the gh
package, which is used for GitHub operations via the REST API. See
gh_token_help() for more about getting and configuring a PAT.
If you use the HTTPS protocol for Git remotes, your PAT is also used for
Git operations, such as
git push. Usethis uses the gert package for this,
so the PAT must be discoverable by gert. Generally gert and gh will
discover and use the same PAT. This ability to "kill two birds with one
stone" is why HTTPS + PAT is our recommended auth strategy for those new
to Git and GitHub and PRs.
If you use SSH remotes, your SSH keys must also be discoverable, in addition to your PAT. The public key must be added to your GitHub account.
Git/GitHub credential management is covered in a dedicated article: Managing Git(Hub) Credentials