In lwjohnst86/githubr: Interface to GitHub from R

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  eval=FALSE
)
helper_file <- list.files(
    c(".."),
    pattern = "helpers.R",
    full.names = TRUE,
    recursive = TRUE
)
source(tools::file_path_as_absolute(helper_file))

The githubr package is primarily a wrapper around the great gh package to create functions for explicit and simple calls to the API. For instance, if you want to create a new issue to a repository, you can use the function gh_new_issue() rather than tinkering through the GitHub API. The arguments to the functions provide (almost) everything you need when interacting with GitHub! Currently, githubr (and by extension the gh package it is based on) uses the v3 of the API.

The main purpose for this package is to programmatically interact with GitHub activities, such as quickly creating issues for multiple problems, deleting labels and using other labels (e.g. less software focused), or making edits to existing issues.

A big assumption about using githubr is that you are authenticated with GitHub via a Personal Access Token.

Authenticating: Obtaining a GitHub PAT

Before you can really start using githubr, you need to get authenticated with GitHub. Nearly all githubr functions require a GitHub PAT, or Personal Access Token. The PAT is obtained through a GITHUB_PAT R environment variable and can be found by using:

gh::gh_whoami()

If you have it set up, you should see a "token" key-value pair. For more information about PAT, how to get one, and how to set it up in R, check out the usethis::browse_github_pat(). Do this in order to fully make use of the githubr functions.

Functions implemented

The GitHub API is extensive, so not all functions have (or will be) implemented to fully interact with GitHub. If you want to make an API request for items not listed in the two tables below, head over to the gh package to be able to do what you want.

# Extract functions documentation data
func_data <- .rd_as_data_for_table()

# Keep only those exposed to users and print table
funs_impl <- .functions_implemented(func_data)
.table_of_functions(funs_impl, caption = "Implemented githubr functions.")

Creating, editing, and listing issues

Working with issues is easy! Have a repository and you want to see what issues are available?

Note: The code output isn't included since each function used calls the GitHub API, which has strict limits on using their service (for good security reasons). So this documentation doesn't include the output.

library(githubr)
gh_list_issues("lwjohnst86/carpenter")

What about checking out all the labels?

repository <- "lwjohnst86/test-githubr"
gh_list_labels(repository)

You can even add another label (and delete it if you want).

gh_create_label(repository, "Interesting", "deadad")
# Then delete it
gh_delete_label(repository, "Interesting")

Want to create a new issue? Easy too!

gh_new_issue(repository, title = "Making an issue", labels = c("bug", "wontfix"))

Functions to be implemented

There are of course several functions that will eventually be implemented. Here is a list of functions planned to be implemented at some point in the future.

# Keep those not exposed and remove internal functions and print table
funs_to_impl <- .functions_to_implement(func_data)
.table_of_functions(funs_to_impl, caption = "Functions to still implement in githubr.")

lwjohnst86/githubr documentation built on Aug. 17, 2020, 3:37 a.m.