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 master

    • No uncommitted changes

    • No pre-existing origin remote

  • Creates an associated repo on GitHub

  • Adds that GitHub repo to your local repo as the origin remote

  • 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

  • Configures origin/master to be the upstream branch of the local master branch

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()
)

Arguments

organisation

If supplied, the repo will be created under this organisation, instead of the account of the user associated with the auth_token. You must have permission to create repositories.

private

If TRUE, creates a private repository.

protocol

Optional. Should be "https" or "ssh", if specified. Defaults to the option usethis.protocol and, if unset, to an interactive choice or, in non-interactive sessions, "https". NA triggers the interactive menu.

auth_token

GitHub personal access token (PAT).

host

GitHub API host to use. Override with the endpoint-root for your GitHub enterprise instance, for example, "https://github.hostname.com/api/v3".

credentials

Defunct lifecycle : 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.

Authentication

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 create_github_token().

  • Provide the token directly via the auth_token argument.

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 option.

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.

Examples

if (FALSE) { pkgpath <- file.path(tempdir(), "testpkg") create_package(pkgpath) ## now, working inside "testpkg", initialize git repository use_git() ## create github repository and configure as git remote use_github() }