{gitlabr} v2.0 is on CRAN!

You regularly create projects on GitLab with a common skeleton, you want to retrieve the list of GitLab issues to create a report, you are looking for batch modifications of your projects? Use the GitLab API from your preferred programming language R.

Communicate with GitLab API from R

Here is a small example as issued from the {gitlabr} Readme on GitHub:

• Create a TOKEN on your GitLab instance with scopes: api
  • For instance on gitlab.com: https://gitlab.com/-/profile/personal_access_tokens
• Store your token in “.Renviron” as GITLAB_COM_TOKEN with usethis::edit_r_environ() and restart your session
• Set a connection to GitLab instance

library(gitlabr)
# You can verify your token works
# Sys.getenv("GITLAB_COM_TOKEN")
# connect as a fixed user to a GitLab instance for the session
set_gitlab_connection(
  gitlab_url = "https://gitlab.com",
  private_token = Sys.getenv("GITLAB_COM_TOKEN"))

• Find the list of projects available to you
  • Define a limit of pages of projects to search in with max_page, otherwise the entire GitLab.com will be downloaded here…

# a tibble is returned, as always with {gitlabr} functions
gl_list_projects(max_page = 1) 

## # A tibble: 20 x 99
##    id     description   name     name_with_namespace path    path_with_namespace created_at
##    <chr>  <chr>         <chr>    <chr>               <chr>   <chr>               <chr>     
##  1 28743… ""            gitlab … Hari Prasad APTO T… gitlab… hariapto/gitlab-pr… 2021-08-0…
##  2 28743… ""            account… oanh phạm / accoun… accoun… oanhpham/account-m… 2021-08-0…
##  3 28743… ""            fptapte… Quốc Nguyễn Văn / … fptapt… 0353450903/fptapte… 2021-08-0…
##  4 28743… "Environment… Environ… Jared Kozak / Envi… enviro… jaredkozak/environ… 2021-08-0…
##  5 28743… ""            devsingh Erica / devsingh    devsin… erica.rajput/devsi… 2021-08-0…
##  6 28743… ""            firechat prem m / firechat   firech… prem2201/firechat   2021-08-0…
##  7 28743… "An easy gam… GO-Supe… Nestor Calvo / GO-… GO-Sup… nestorcalvo/GO-Sup… 2021-08-0…
##  8 28743…  <NA>         civil e… Civil engineering … civil-… civil-engineering/… 2021-08-0…
##  9 28743… "After colla… Stealth… Bvayper / StealthT… STG     bvayper/STG         2021-08-0…
## 10 28743… ""            Bukan D… Dimas Mahendra Kus… bukan-… dimassmacip/bukan-… 2021-08-0…
## 11 28743… ""            flask-r… CloudNua-Public / … flask-… cloudnua-public/fl… 2021-08-0…
## 12 28743… ""            jarvis_… Muhammad Yahya Abd… jarvis… Yahya1011/jarvis_f… 2021-08-0…
## 13 28743… ""            Clj Res… Rok Lenarcic / Clj… clj-re… rok.lenarcic/clj-r… 2021-08-0…
## 14 28743… "Project wit… project… gitlab-qa-sandbox-… projec… gitlab-qa-sandbox-… 2021-08-0…
## 15 28743…  <NA>         Fructus  Sotheavuth Nguon /… Fructus sotheavuthnguon/Fr… 2021-08-0…
## 16 28743… "My awesome … project… gitlab-qa-sandbox-… projec… gitlab-qa-sandbox-… 2021-08-0…
## 17 28743… "project for… project… gitlab-qa-sandbox-… projec… gitlab-qa-sandbox-… 2021-08-0…
## 18 28743… ""            non-pro… Kundan Bapat / non… non-pr… kbapat2/non-produc… 2021-08-0…
## 19 28743… "Project wit… project… gitlab-qa-sandbox-… projec… gitlab-qa-sandbox-… 2021-08-0…
## 20 28743… ""            site-se… service_portal / s… site-s… service_portal/sit… 2021-08-0…
## # … with 92 more variables: default_branch <chr>, ssh_url_to_repo <chr>,
## #   http_url_to_repo <chr>, web_url <chr>, readme_url <chr>, forks_count <chr>,
## #   star_count <chr>, last_activity_at <chr>, namespace.id <chr>, namespace.name <chr>,
## #   namespace.path <chr>, namespace.kind <chr>, namespace.full_path <chr>,
## #   namespace.avatar_url <chr>, namespace.web_url <chr>,
## #   container_registry_image_prefix <chr>, _links.self <chr>, _links.issues <chr>,
## #   _links.merge_requests <chr>, _links.repo_branches <chr>, _links.labels <chr>,
## #   _links.events <chr>, _links.members <chr>, packages_enabled <chr>, empty_repo <chr>,
## #   archived <chr>, visibility <chr>, owner.id <chr>, owner.name <chr>,
## #   owner.username <chr>, owner.state <chr>, owner.avatar_url <chr>, owner.web_url <chr>,
## #   container_expiration_policy.enabled <chr>, container_expiration_policy.keep_n <chr>,
## #   container_expiration_policy.older_than <chr>,
## #   container_expiration_policy.name_regex <chr>,
## #   container_expiration_policy.next_run_at <chr>, issues_enabled <chr>,
## #   merge_requests_enabled <chr>, wiki_enabled <chr>, jobs_enabled <chr>,
## #   snippets_enabled <chr>, container_registry_enabled <chr>, service_desk_enabled <chr>,
## #   service_desk_address <chr>, can_create_merge_request_in <chr>,
## #   issues_access_level <chr>, repository_access_level <chr>,
## #   merge_requests_access_level <chr>, forking_access_level <chr>,
## #   wiki_access_level <chr>, builds_access_level <chr>, snippets_access_level <chr>,
## #   pages_access_level <chr>, operations_access_level <chr>, analytics_access_level <chr>,
## #   container_registry_access_level <chr>, shared_runners_enabled <chr>,
## #   lfs_enabled <chr>, creator_id <chr>, import_status <chr>, open_issues_count <chr>,
## #   ci_default_git_depth <chr>, ci_forward_deployment_enabled <chr>,
## #   ci_job_token_scope_enabled <chr>, public_jobs <chr>, build_timeout <chr>,
## #   auto_cancel_pending_pipelines <chr>, ci_config_path <chr>,
## #   only_allow_merge_if_pipeline_succeeds <chr>, restrict_user_defined_variables <chr>,
## #   request_access_enabled <chr>, only_allow_merge_if_all_discussions_are_resolved <chr>,
## #   remove_source_branch_after_merge <chr>, printing_merge_request_link_enabled <chr>,
## #   merge_method <chr>, squash_option <chr>, auto_devops_enabled <chr>,
## #   auto_devops_deploy_strategy <chr>, autoclose_referenced_issues <chr>,
## #   keep_latest_artifact <chr>, approvals_before_merge <chr>, mirror <chr>,
## #   security_and_compliance_enabled <chr>, merge_pipelines_enabled <chr>,
## #   merge_trains_enabled <chr>, namespace.parent_id <chr>

Work with a specific GitLab project

• Explore one of your projects. You can set the name of the project or its ID. The ID is highly recommended, in particular if your project does not appear in the first pages of projects above.
  • Let’s explore project “repo.rtask”, with ID = 20384533 on GitLab.com

my_project <- 20384533 #repo.rtask",

• If the default branch is not named main, you need to specify it with gitlabr_options_set()

gitlabr_options_set("gitlabr.main", "master")

• List files of the project using gl_list_files()

gl_list_files(project = my_project)

## # A tibble: 2 x 5
##   id                                       name        type  path        mode  
##   <chr>                                    <chr>       <chr> <chr>       <chr> 
## 1 9c66eff9a1f6f34b6d9108ef07d76f8ce4c4e47f NEWS.md     blob  NEWS.md     100644
## 2 c36b681bb31b80cbd090f07c95f09788c88629a6 example.txt blob  example.txt 100644

• List issues with gl_list_issues()

gl_list_issues(project = my_project)

## # A tibble: 2 x 35
##   <chr>  <chr> <chr>      <chr>     <chr>           <chr> <chr>       <chr>       <chr>    
## 1 69525… 2     20384533   A second… The blog post … open… 2020-08-06… 2020-08-06… 4809823  
## 2 69525… 1     20384533   An examp… No desc in iss… open… 2020-08-06… 2020-08-06… 4809823  
## #   merge_requests_count <chr>, upvotes <chr>, downvotes <chr>, confidential <chr>,
## #   issue_type <chr>, web_url <chr>, time_stats.time_estimate <chr>,
## #   time_stats.total_time_spent <chr>, task_completion_status.count <chr>,
## #   task_completion_status.completed_count <chr>, blocking_issues_count <chr>,
## #   has_tasks <chr>, _links.self <chr>, _links.notes <chr>, _links.award_emoji <chr>,
## #   _links.project <chr>, references.short <chr>, references.relative <chr>,
## #   references.full <chr>

Set up GitLab CI with {gitlabr} for R packages or bookdown

{gitlabr} can be used to create a .gitlab-ci.yml file to test, build and check an R package, a bookdown, … using GitLab’s CI software. Use gitlabr::use_gitlab_ci() with a specific type in your project and your CI should be ready to start in the next commit.

There are pre-defined templates:

• bookdown-production.yml
• bookdown.yml
• check-coverage-pkgdown-renv.yml
• check-coverage-pkgdown.yml

Multiple changes since last version

I took upon the development of {gitlabr} so that it continues to be available on CRAN.
Thanks to constructive feedback of Robert M Flight and Jenny Brian, and to important contributions of LDalby and Kevin Cazelles, we have a renewed package with consistent documentation.
Vignettes are still a work in progress, and you are all welcome to participate, but the general idea is defined.

A few changes have been made that can prevent your old workflows to work.
The major one is the hex logo of course!

Breaking changes

• Default branch is named main whenever required.
  • This can be changed with gitlabr_options_set("gitlabr.main", "master")
• All project-specific functions get project as first parameter. Changes apply to:
  • gl_get_comments(),gl_to_issue_id(), gl_get_issue_comments(), gl_get_commit_comments(),
    gl_edit_comment(), gl_edit_issue_comment(), gl_edit_commit_comment()
  • gl_repository()
  • gl_get_issue(), gl_to_issue_id(), gl_new_issue(), gl_create_issue(), gl_edit_issue(), gl_close_issue(),
    gl_reopen_issue(), gl_assign_issue(), gl_unassign_issue()
• Changed use of api_version = "v4" by api_version = 4
• Changed use of force_api_v3 = TRUE by api_version = 4 for deprecation by default

Major changes

• New use of use_gitlab_ci() with pre-defined templates
• Add new functions to manage projects: gl_get_project(), gl_new_project(), gl_edit_project(),
  gl_delete_project()

Minor changes

• gl_archive() is used to archive a project (not to download an archive)
• fix use of max_page with gl_() functions calling gitlab()
• Correction of api that downloaded twice the first page when page == "all"
• Reduce max_page in examples and tests to retrieve content to allow to work with big GitLab servers like Gitlab.com
• Change maintainer

To go further

• All reproducible examples and {gitlabr} documentation are in the pkgdown site: https://statnmap.github.io/gitlabr/
  • Quick Start Guide to {gitlabr}
  • Create and manage a new GitLab project
  • Alternative connections to projects
  • Go further: understand and build your functions
• Some time ago, I wrote: “Download Gitlab or Github issues and make a summary report of your commits”. This uses {gitlabr} et {gitdown}.
• Our “guide to collaborative development with R for reproducible PROPRE reporting” highly relies on GitLab tools. {gitlabr} is a good friend to start project with similar skeletons.