R code using gitlabr to perform some easy, common gitlab actions can look like this:
library(gitlabr) # connect to a gitlab instance my_gitlab <- gl_connection("https://test-gitlab.points-of-interest.cc", private_token = readLines("secrets/gitlab_token.txt")) # a function is returned # its first argument is the request (name or function), optionally followed by parameters my_gitlab(gl_list_projects) my_gitlab(gl_list_files, project = "gitlabr", path = "R") # create a new issue new_feature_issue <- my_gitlab(gl_new_issue, project = "testor", "Implement new feature") # requests via gitlabr always return data_frames, so you can use all common manipulations require(dplyr) example_user <- my_gitlab("users") %>% filter(username == "testuser") # assign issue to a user my_gitlab(gl_assign_issue, project = "testor", new_feature_issue$iid, assignee_id = example_user$id) my_gitlab(gl_list_issues, "testor", state = "opened") # close issue my_gitlab(gl_close_issue, project = "testor", new_feature_issue$iid)$state
gitlabr
provides a high and a low level interface to the gitlab API at the same time:gitlabr
function is a data_frame
to integrate seamless into dplyr's data manipulation mindset (often called the "tidyverse")page
and per_page
if necessary.gitlabr
you can do using any of a set of general idioms -- get to know them in the section "Different ways to do it".gitlabr
logic following only one principle as described in the section "Writing custom gitlab request functions".This section describes how R function calls are translated into HTTP requests to the gitlab API (gitlabr
's "low level interface"). For a documentation using gitlabr
without knowledge of the gitlab API (gitlabr
's "high level interface"), see the "Quick Start Example" above, the "Convenience function list" below or the individual function documentation.
The core function of the low level interface is gitlab
, with the help of which arbitrary calls to the gitlab API can be formulated. It takes as required arguments the request location as a character vector, API endpoint URL and HTTP verb and passes additional arguments as query parameters (keeping their names) on to the API request.
gitlab(c("projects", 12, "issues"), api_root = "https://gitlab.points-of-interest.cc/api/v3", private_token = "XXX", # authentication for API verb = httr::GET, # defaults to GET, but POST, PUT, DELETE can be used likewise state = "active") # additional parameters (...) for the query
translates to
GET https://gitlab.points-of-interest.cc/api/v4/projects/12/issues?state=active&private_token=XXX
This way, any request documented in the Gitlab API documentation can be issued from gitlabr
.
The high level interface consists of a number of functions that each have additional
arguments from which the request location is constructed, while all other arguments are simply passed on to gitlab
. For example:
gl_edit_issue(project = "test-project", 12, description = "Really cool new feature", api_root = "...", private_token = "XXX")
does nothing but
gitlab(c("projects", 4, # numeric id of test-project is found by search "issues", 12), description = "Really cool new feature", api_root = "...", private_token = "XXX", verb = httr::PUT))
and hence translates to
PUT .../projects/4/issues/12?private_token=XXX?description=Really%20cool%20new%20feature
To spare you the repetitive task of specifying the API root and key in every call, you can use gitlab_connection
as described in the next section "Different ways to do it".
Note: currently (gitlabr version 1.1.6) gitlab API v4 is supported. Support for Gitlab API v3 (for Gitlab version < 9.0) is still included via flag parameters, but is no longer maintained. For details see the section "API version" of the documentation of gl_connection
.
gitlabr
is implemented following the functional programming paradigm. Several of its functions return or accept functions as arguments. This results in huge flexibility in how API requests using gitlabr
can be formulated in your R code. Three major styles are described below, after introducing the central mechanism of creating more specific API connection functions.
The idea of connections in gitlabr
is to generate functions with the same signature and capability of the central API call function gitlab
, but with certain parameters set to fixed values ("curried"). This way these more specialized functions represent and provide the connection -- for example -- to a specific gitlab instance as a specific user. Such specialized functions can be created by the function gitlab_connection
and then used exactly as you would use gitlab
:
my_gitlab <- gl_connection("https://test-gitlab.points-of-interest.cc", private_token = readLines("secrets/gitlab_token.txt")) my_gitlab("projects")
require(dplyr) my_gitlab("projects") %>% filter(public == "TRUE") %>% select(name, everything())
gitlab_connection
can take arbitrary parameters, returning a function that issues API requests with these parameter values set.
As a convenience wrapper to directly connect to a specific project in a gitlab instance, project_connection
exists.
For combining so created gitlab connections with the convenience functions to perform common tasks, several possible styles/idioms exist:
Instead of the query as character vector gitlab
and thus also all connections accept equivalently a function as first argument, that is then called with the additional parameters and using the connection for all API calls:
my_gitlab(gl_new_issue, "Implement new feature", project = "testor")
gl_new_issue
is an example function here, the principle style works for all convenience functions of gitlabr
listed in the "Convenience function list" below or user-defined functions as described in the section "Writing custom gitlab request functions".
Some of the convenience perform additional transformation or renaming of parameters. Hence, the parameters given to the exemplary my_gitlab(...)
call after the function should be valid according the documentation of the respective function and may differ from names used in the gitlab API itself, although this is the case only in very few cases.
Alternatively, gitlab
as well as all convenience wrappers accept a parameter gitlab_con
specifying the function to use for the actual API call. Hence, you can pass a gitlab connection (as returned by gl_connection
) with the R function call:
gl_new_issue("Implement new feature", project = "testor", gitlab_con = my_gitlab)
Again, gl_new_issue
is an example function here, the principle style works for all convenience functions of gitlabr
listed in the "Convenience function list" below or user-defined functions as described in the section "Writing custom gitlab request functions".
In order to avoid the repeated specification of gitlab_con
in the parameter style, you can also set a global variable managed by gitlabr to use a specific connection function for every call:
set_gitlab_connection(my_gitlab) gl_new_issue("Implement new feature", project = "testor")
Again, gl_new_issue
is an example function here, the principle style works for all convenience functions of gitlabr
listed in the "Convenience function list" below or user-defined functions as described in the section "Writing custom gitlab request functions".
Note that the set style is not purely functional, since set_gitlab_connection
changes a saved global variable affecting the results of all future gitlab
calls. You can reset this variable to the default value using unset_gitlab_connection()
.
Here is a list of all convenience wrapper functions that come with gitlabr
1.1.6. Only function names are given, since they are designed to be self-explanatory. For reference on how to use each function, refer to its R documentation using the ?
operator.
Note: There are more locations and actions that can be accessed through the gitlab API. See the documentation of the Gitlab API for this. The next section describes how you can write your own convenience wrappers that work with all styles described in the section "Different ways to do it".
Note also that since gitlabr version 0.7 all functions of this package follow a consistent naming scheme, starting with gl_
. The old function names are deprecated and might be removed without further notice.
It is very easy to write your own convenience wrappers for accessing API endpoints you whish and make sure they fully integrate into gitlabr
and work conveniently with all connection and call idioms described in this vignette. The only requirement to your function is that it executes an R function call to gitlab
(or another convenience function) to which the ...
argument is passed on.
That is, a simple function to block users directly from R is as simple as:
gl_block_user <- function(uid, ...) { gitlab(c("users", uid, "block"), ## for API side documentation see: verb = httr::PUT, ## https://doc.gitlab.com/ce/api/users.html#block-user ...) ## don't forget the dots to make gitlabr features fully available }
More hints for more convenience:
gitlabr
principle, make sure your function returns a data_frame
(which it does if you simply pass up the return value of gitlab
or one of the package's own convenience functions). gitlab
has some heuristics to format the API response to a data_frame
, if these fail for your specific request, you can pass auto_format = FALSE
and format the response manually.gitlabr
's internal functions proj_req
translating the request location.gitlabr
's internal function to_issue_id
when constructing the request.And last but not least, if you've written a convenience wrapper for yourself, keep in mind that it might be of help to many others and you can contribute it to gitlabr
on https://github.com/jirkalewandowski/gitlabr/.
gitlabr
can also be used to create a .gitlab-ci.yml
file to test, build and check an R package using gitlabs CI software. See the use_gitlab_ci
and related functions for documentation.
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.