R: Connect a local repo with GitHub

use_github {usethis} | R Documentation

## 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"`: `git@github.com:<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

    ## End(Not run)

[Package usethis version 1.4.0 Index]