usethis (version 1.4.0)

use_github: Connect a local repo with GitHub

Description

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.

Usage

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

Arguments

organisation

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

private

If TRUE, creates a private repository.

protocol

transfer protocol, either "ssh" (the default) or "https"

credentials

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

auth_token

Provide a personal access token (PAT) from https://github.com/settings/tokens. 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.

host

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

Authentication

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": [e-mail]:<OWNER>/<REPO>.git

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

For protocol = "ssh", it is assumed that public and private keys are in the default locations, ~/.ssh/id_rsa.pub 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.

Examples

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

## now, working inside "testpkg", initialize git repository
use_git()

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