Request GitLab API

This is 'gitlabr' core function to talk to GitLab's server API via HTTP(S). Usually you will not use this function directly too often, but either use 'gitlabr' convenience wrappers or write your own. See the 'gitlabr' vignette for more information on this.

gitlab(
  req,
  api_root,
  verb = httr::GET,
  auto_format = TRUE,
  debug = FALSE,
  gitlab_con = "default",
  page = "all",
  max_page = 10,
  enforce_api_root = TRUE,
  argname_verb = if (identical(verb, httr::GET) || identical(verb, httr::DELETE)) {
    
    "query"
 } else {
     "body"
 },
  ...
)

Arguments

req

vector of characters that represents the call (e.g. c("projects", project_id, "events"))

api_root

URL where the GitLab API to request resides (e.g. https://gitlab.myserver.com/api/v3/)

verb

http verb to use for request in form of one of the httr functions httr::GET(), httr::PUT(), httr::POST(), httr::DELETE()

auto_format

whether to format the returned object automatically to a flat data.frame

debug

if TRUE API URL and query will be printed, defaults to FALSE

gitlab_con

function to use for issuing API requests (e.g. as returned by get_gitlab_connection()

page

number of page of API response to get; if "all" (default), all pages (up to max_page parameter!) are queried successively and combined.

max_page

maximum number of pages to retrieve. Defaults to 10. This is an upper limit to prevent 'gitlabr' getting stuck in retrieving an unexpectedly high number of entries (e.g. of a project list). It can be set to NA/Inf to retrieve all available pages without limit, but this is recommended only under controlled circumstances.

enforce_api_root

if multiple pages are requested, the API root URL is ensured to be the same as in the original call for all calls using the "next page" URL returned by GitLab This makes sense for security and in cases where GitLab is behind a reverse proxy and ignorant about its URL from external.

argname_verb

name of the argument of the verb that fields and information are passed on to

...

named parameters to pass on to GitLab API (technically: modifies query parameters of request URL), may include private_token and all other parameters as documented for the GitLab API

Value

the response from the GitLab API, usually as a tibble and including all pages

Details

gitlab() function allows to use any request of the GitLab API https://docs.gitlab.com/ce/api/.

For instance, the API documentation shows how to create a new project in https://docs.gitlab.com/ce/api/projects.html#create-project:

• The verb is POST

• The request is projects

• Required attributes are name or path (if name not set)

• default_branch is an attribute that can be set if wanted

The corresponding use of gitlab() is:

gitlab(
  req = "projects",
  verb = httr::POST,
  name = "toto",
  default_branch = "main"
)

Note: currently GitLab API v4 is supported. GitLab API v3 is no longer supported, but you can give it a try.

Examples

if (FALSE) {
# Connect as a fixed user to a GitLab instance
set_gitlab_connection(
  gitlab_url = "https://gitlab.com",
  private_token = Sys.getenv("GITLAB_COM_TOKEN")
)

# Use a simple request
gitlab(req = "projects")
# Use a combined request with extra parameters
gitlab(
  req = c("projects", 1234, "issues"),
  state = "closed"
)
}