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. master or main

    • 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

  • Makes an initial push to GitHub

  • Calls use_github_links(), if the project is an R package

  • Configures origin/DEFAULT to be the upstream branch of the local DEFAULT branch, e.g. master or main

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

Arguments

organisation

If supplied, the repo will be created under this organisation, instead of the login associated with the GitHub token discovered for this host. The user's role and the token's scopes must be such that you have permission to create repositories in this organisation.

private

If TRUE, creates a private repository.

protocol

One of "https" or "ssh"

host

GitHub host to target, passed to the .api_url argument of gh::gh(). If unspecified, gh defaults to "https://api.github.com", although gh's default can be customised by setting the GITHUB_API_URL environment variable.

For a hypothetical GitHub Enterprise instance, either "https://github.acme.com/api/v3" or "https://github.acme.com" is acceptable.

auth_token, credentials

Defunct lifecycle : 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 host, as retrieved by gh::gh_token().

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. See gh_token_help() for 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.

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