Creating connections

The recommended way to set a connection once and for all to a specific GitLab instance during your session is to use set_gitlab_connection() as specified in the quick start guide vignette.

set_gitlab_connection(
  gitlab_url = "https://gitlab.com",
  private_token = Sys.getenv("GITLAB_COM_TOKEN"))

However, if you are looking for connections to multiple GitLab instances in the same session or would like to set different accounts, you can define connections using gl_connection().

The idea of connections in {gitlabr} is to generate functions with the same signature and capability as that 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 with the function gl_connection() and then used exactly as you would use gitlab():

my_gitlab <- gl_connection("https://gitlab.com",
                           private_token = Sys.getenv("GITLAB_COM_TOKEN"))
my_gitlab("projects")

gl_connection() can take arbitrary parameters, returning a function that issues API requests with these parameter values.

Similarly, gl_project_connection() can be used as a convenience wrapper to directly connect to a specific project in a GitLab instance.

function-in-function style

The recommended way to use {gitlabr} functions is to directly use gl_*() function after setting the set_gitlab_connection(). For instance with gl_create_issue().

gl_create_issue(project = "<my-project-id>", title = "Implement new feature")

When using custom connections, as for calling the gitlab() function, the query is passed through the req argument as a vector of characters (e.g. “projects”).

my_gitlab(req = c("projects", "<my-project-id>", "issues"))

Another option is to pass a function to the req argument that will then be called along with the additional parameters, using the connection for all API calls :

my_gitlab(gl_create_issue, title = "Implement new feature", project = "<my-project-id>")

gl_create_issue() is an example function here, the principle style works for all convenience functions of {gitlabr} starting with gl_*().

Some of the convenience functions perform additional transformation or renaming of parameters. Hence, the parameters given to the exemplary my_gitlab(...) call after the function should be valid according to the specified function’s documentation, and may differ from names used in the GitLab API itself, although this occurs only very rarely.

Define a custom function with `gitlab()` and a temporary connection

All API possibilities are not available in {gitlabr}. You can look at vignette “Go further: understand and build your functions” if you want to build your own API function.
Using a gitlab(), out of the recommended way for connection, requires using the gitlab_con parameter as follows.

gitlab(
  c("projects", "<my-project-id>", "issues"),
  gitlab_con = gl_connection("https://gitlab.com",
                           private_token = Sys.getenv("GITLAB_COM_TOKEN"))
)

Alternative connections to projects

Creating connections

function-in-function style

Define a custom function with gitlab() and a temporary connection

Define a custom function with `gitlab()` and a temporary connection