Access to the Gitlab API

Provides R functions to access the API of the project and repository management web application gitlab. For many common tasks (repository file access, issue assignment and status, commenting) convenience wrappers are provided, and in addition the full API can be used by specifying request locations. Gitlab is open-source software and can be self-hosted or used on gitlab.com.


Travis-CI Build Status CRAN_Status_Badge CRAN\ Downloads\ Badge

Installation

You can install the most recent stable version from CRAN using:

install.packages("gitlabr")

To install the development version, in a console type:

git clone https://github.com/jirkalewandowski/gitlabr.git
R -e "library(devtools); document('gitlabr'); install('gitlabr')"

Recommended Gitlab versions & Roadmap

Gitlab 9.0 or higher is generally recommended when using gitlabr version 0.9 or higher, since this package version uses the gitlab API v4, older versions use API v3, which was the standard before Gitlab 9.0. Older versions of Gitlab using API v3 are sill supported by gitlabr 0.9, see details section "API version" of the documentation of gl_connection on how to use them. From gitlabr 1.0 on (expected in the second half of 2017), API v3 usage will be deprecated.

Quick Start Example

R code using gitlabr to perform some easy, common gitlab actions can look like this:

library(gitlabr)
 
# connect as a fixed user to a gitlab instance
my_gitlab <- gl_connection("https://gitlab.points-of-interest.cc",
                           login = "testibaer",
                           password = readLines("secrets/gitlab_password.txt"))
# a function is returned
# its first argument is the request (name or function), optionally followed by parameters
 
my_gitlab(gl_list_projects) # a data_frame is returned, as is always by gitlabr functions
 
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 == "testibaer")
 
# 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

Further information

  • For a comprehensive overview & introduction see the vignette("quick-start-gitlabr")
  • When writing custom extensions ("convenience functions") for gitlabr or when you experience any trouble, the very extensive Gitlab API documentation can be helpful.
  • gitlabr is developed on https://gitlab.points-of-interest.cc/points-of-interest/gitlabr -- Github and Gitlab.com are mirrors of this repository, but can be used for filing issues or merge requests.

News

gitlabr 0.9 (2017-04-24)

  • Support for Gitlab API v4 (default from Gitlab version 9.0 onwards) was added. Gitlab API v4 is now the default used by gitlabr, but using the old API (v3) is still possible, see details section "API version" of the documentation of gl_connection.
    • Several convenience functions now have a force_api_v3 parameter to force old API version logic.
    • Issues are now identified by project-wide id and not global iid, according to API v4 logic.
    • Function gl_builds was replaced by gl_pipelines and gl_jobs to reflect API v4 logic.
  • push_to_remotes parameter was added to use_gitlab_ci such that gitlab CI can be used conveniently for pushing to remote repositories.
  • Examples were added to almost all function reference pages.
  • In case of Server Error (HTTP Status 5xx), gitlabr now performs up to 3 retries, waiting 25 secondes in between. This is mostly to catch errors due to slow server responses, when the packages test suite is run.

gitlabr 0.8

There is no gitlabr 0.8. Version number 0.9 was used to align with Gitlab version 9.0, for which this version is appropriate.

gitlabr 0.7 (2017-03-06)

  • All functions were renamed to a new scheme starting with "gl_"
  • A shiny module with gitlab login was added
  • CI access functions were added
  • Added a NEWS.md file to track changes to the package.

Reference manual

It appears you don't have a PDF plugin for this browser. You can click here to download the reference manual.