use_github() takes a local project, creates an associated repo on GitHub, adds it to your local repo as the origin remote, and makes an initial push to synchronize. use_github() requires that your project already be a Git repository, which you can accomplish with use_git(), if needed. See the Authentication section below for other necessary setup.

use_github(organisation = NULL, private = FALSE,
  protocol = getOption("usethis.protocol", default = "ssh"),
  credentials = NULL, auth_token = NULL, host = NULL)



If supplied, the repo will be created under this organisation. You must have access to create repositories.


If TRUE, creates a private repository.


transfer protocol, either "ssh" (the default) or "https". You can supply a global default with options(usethis.protocol = "https").


A git2r::cred_ssh_key() specifying specific ssh credentials or NULL for default ssh key and ssh-agent behaviour.


Provide a personal access token (PAT) from If NULL, will use the logic described in gh::gh_whoami() to look for a token stored in an environment variable. Use browse_github_pat() to help set up your PAT.


GitHub API host to use. Override with the endpoint-root for your GitHub enterprise instance, for example, ""


A new GitHub repo will be created via the GitHub API, therefore you must make a GitHub personal access token (PAT) available. You can either provide this directly via the auth_token argument or store it in an environment variable. Use browse_github_pat() to get help obtaining and storing your PAT. See gh::gh_whoami() for even more detail.

The argument protocol specifies the transport protocol you wish to use for this repo in the long run. This determines the form of the URL for the origin remote:

  • protocol = "ssh":<OWNER>/<REPO>.git

  • protocol = "https":<OWNER>/<REPO>.git

For protocol = "ssh", it is assumed that public and private keys are in the default locations, ~/.ssh/ and ~/.ssh/id_rsa, respectively, and that ssh-agent is configured to manage any associated passphrase. Alternatively, specify a git2r::cred_ssh_key() object via the credentials parameter. Read more about ssh setup in Happy Git, especially the troubleshooting section.

You can change the default globally with options(usethis.protocol = "https").


pkgpath <- file.path(tempdir(), "testpkg")
create_package(pkgpath) # creates package below temp directory

## now, working inside "testpkg", initialize git repository

## create github repository and configure as git remote
use_github()                   ## to use default ssh protocol
use_github(protocol = "https") ## to use https
# }