usethis (version 1.2.0)

use_github: Connect a local repo with GitHub.

Description

use_github() requires that your package have a git repository, which you can create with use_git(), if needed. use_github() then sets up appropriate git remotes and syncs. use_github_links() populates the URL and BugReports fields with appropriate links (unless they already exist).

Usage

use_github(organisation = NULL, private = FALSE, protocol = c("ssh",
  "https"), credentials = NULL, auth_token = NULL, host = NULL)
use_github_links(auth_token = NULL, host = "https://api.github.com")

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. Default is NULL.

auth_token

Provide a personal access token (PAT) from https://github.com/settings/tokens. If NULL, will use the GITHUB_PAT environment variable.

host

GitHub API host to use. Override with the endpoint-root for your GitHub enterprise instance, for example, "https://github.hostname.com/api/v3". You can set this globally using the GITHUB_API_URL env var.

Authentication

A new GitHub repo will be created via the GitHub API, therefore you must provide a GitHub personal access token (PAT) via the argument auth_token, which defaults to the value of the GITHUB_PAT environment variable. Obtain a PAT from https://github.com/settings/tokens. The "repo" scope is required which is one of the default scopes for a new PAT.

The argument protocol reflects how you wish to authenticate with GitHub for this repo in the long run. For either protocol, a remote named "origin" is created, an initial push is made using the specified protocol, and a remote tracking branch is set. The URL of the "origin" remote has the form [e-mail]:<USERNAME>/<REPO>.git (protocol = "ssh", the default) or https://github.com/<USERNAME>/<REPO>.git (protocol = "https"). 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.

Examples

# NOT RUN {
create_package("test-pkg") # creates package in current working directory

## now, working inside "test-pkg", 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
# }