gitlab: Request GitLab API

In gitlabr: Access to the 'Gitlab' API

Request GitLab API

Description

This is gitlabr's 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's convenience wrappers or write your own. See the gitlabr vignette for more information on this.

Usage

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 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

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.

Value

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

Examples

## Not run: 
# 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")

## End(Not run)

gitlabr documentation built on Sept. 13, 2022, 5:06 p.m.