wflow_use_github: Deploy site with GitHub

In jdblischak/workflowr: A Framework for Reproducible and Collaborative Data Science

Deploy site with GitHub

Description

wflow_use_github automates all the local configuration necessary to deploy your workflowr project with GitHub Pages. Optionally, it can also create the new repository on GitHub (only applies to public repositories hosted on github.com). Afterwards, you will need to run wflow_git_push in the R console (or git push in the terminal) to push the code to GitHub.

Usage

wflow_use_github(
  username = NULL,
  repository = NULL,
  organization = NULL,
  navbar_link = TRUE,
  create_on_github = NULL,
  protocol = "https",
  domain = "github.com",
  project = "."
)

Arguments

username	character (default: NULL). The GitHub account associated with the GitHub repository. This should be your personal GitHub username. If the repository will be created for a GitHub organization, instead use the argument organization. It will be combined with the arguments repository and domain to determine the URL of the new repository, e.g. the default is https://github.com/username/repository. It will be combined with the arguments repository, domain, and protocol to determine the URL for Git to use to push and pull from GitHub, e.g. the default is https://github.com/username/repository.git. If username is not specified, wflow_use_github will first attempt to guess it from the current setting for the remote URL named "origin". If you haven't previously configured a remote for this workflowr project (or you are unsure what that means), then you should specify your GitHub username when calling this function.
repository	character (default: NULL). The name of the remote repository on GitHub. If not specified, workflowr will guess the name of the repository. First, it will check the current setting for the remote URL named "origin". Second, it will use the name of the root directory of the workflowr project.
organization	character (default: NULL). The GitHub organization associated with the GitHub repository. Only set one of organization or username. See the argument username above for more details.
navbar_link	logical (default: TRUE). Insert a link to the GitHub repository into the navigation bar.
create_on_github	logical (default: NULL). Should workflowr create the repository on GitHub? This requires logging into your GitHub account to authenticate workflowr to act on your behalf. The default behavior is to ask the user. Note that this only works for public repositories on github.com. If you want to create a private repository or are using GitHub Enterprise, you will need to manually create the repository.
protocol	character (default: "https"). The protocol for communicating with GitHub. Must be either "https" or "ssh".
domain	character (default: "github.com"). The domain of the remote host. You only need to change this if your organization is using GitHub Enterprise.
project	character (default: ".") By default the function assumes the current working directory is within the project. If this is not true, you'll need to provide the path to the project directory.

Details

wflow_use_github performs the following steps and then commits the changes:

• Adds a link to the GitHub repository in the navigation bar

• Configures the Git remote settings to use GitHub (via wflow_git_remote)

• (Only if necessary) Renames the website directory to docs/

• (Only if necessary) Edits the setting output_dir in the file _site.yml to save the website files in docs/

Furthermore, you have two options for creating the remote repository on GitHub. In an interactive R session, you will be prompted to choose one of the options below. To bypass the prompt, you can set the argument create_on_github.

• 1. Have workflowr create the new repository on GitHub. If you accept, your browser will open for you to provide authorization. If you are not logged into GitHub, you will be prompted to login. Then you will be asked to give permission to the workflowr-oauth-app to create the new repository for you on your behalf. This will allow wflow_use_github, running on your own machine, to create your new repository. Once wflow_use_github finishes, workflowr can no longer access your GitHub account.

• 2. Create the remote repository yourself by going to https://github.com/new and entering the Repository name that matches the name of the directory of your workflowr project (if you used the argument repository to make it a different name, make sure to instead use that one).

Once the GitHub repository has been created either by wflow_use_github or yourself, run wflow_git_push in the R console (or git push origin master in the terminal) to push your code to GitHub.

Value

Invisibly returns a list of class wflow_use_github. This is currently for internal use only. Please open an Issue if you'd like to use this information.

Troubleshooting

The feature to automatically create the GitHub repository for you may fail since it involves using your web browser to authenticate with your GitHub account. If it fails for any reason, it'd probably be easier to manually login to GitHub and create the repository yourself (instructions from GitHub). However, if you have time, please file an Issue on GitHub to report what happened, and importantly include which web browser you were using.

We have observed the following problems before:

• The green button to approve the authentication of the workflowr GitHub app to create the repository on your behalf is grayed out, and unable to be clicked. This is likely a JavaScript problem. Make sure you don't have JavaScript disabled in your web browser. Also, you can try using a different browser.

See Also

wflow_git_push, wflow_git_remote, wflow_use_gitlab

Examples

## Not run: 

wflow_use_github("your-username", "name-of-repository")
# Login with GitHub account and create new repository
wflow_git_push()

# Create a repository for an organization  you belong to
wflow_use_github(organization = "my-org")

## End(Not run)

jdblischak/workflowr documentation built on Nov. 26, 2024, 5:14 p.m.