Connect a local repo with GitHub

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.

use_github_links() populates the URL and BugReports fields of a GitHub-using R package with appropriate links (unless they already exist).

use_github(organisation = NULL, private = FALSE, protocol = c("ssh",
  "https"), credentials = NULL, auth_token = NULL, host = NULL)

use_github_links(auth_token = NULL, host = "")


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"


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 reflects how you wish to authenticate with GitHub for this repo in the long run. This determines the form of the URL for the origin remote:

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

  • protocol = "https":<USERNAME>/<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.

  • use_github
  • use_github_links
create_package("test-pkg") # creates package in current working directory

## now, working inside "test-pkg", 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
# }
Documentation reproduced from package usethis, version 1.3.0, License: GPL-3

Community examples

Looks like there are no examples yet.