{gitlabr} v2.0 est sur CRAN!

Vous créez régulièrement des projets sur GitLab avec une trame commune, vous voulez récupérer la liste des issues GitLab pour créer un rapport, vous voulez faire des modifications par lots de vos projets ? Utilisez l’API GitLab depuis votre langage de programmation préféré R.

Communiquer avec l’API GitLab depuis R

Voici un petit exemple tiré du {gitlabr} Readme on GitHub :

• Créez un TOKEN sur votre instance GitLab avec le “scope” : api.
  • Pour une instance sur gitlab.com : https://gitlab.com/-/profile/personal_access_tokens
• Stockez votre token dans “.Renviron” sous le nom de GITLAB_COM_TOKEN avec usethis::edit_r_environ() et redémarrez votre session.
• Établissez une connexion à l’instance GitLab

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

• Trouvez la liste des projets à votre disposition
  • Définissez une limite de pages de projets à rechercher avec max_page, sinon l’intégralité de GitLab.com sera téléchargée ici…

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

## # A tibble: 20 x 120
##    id     description       name    name_with_namespa… path   path_with_namesp… created_at 
##    <chr>  <chr>             <chr>   <chr>              <chr>  <chr>             <chr>      
##  1 28744… ""                Conect… Oscar Daniel Vela… conec… somostinn/conect… 2021-08-09…
##  2 28744… ""                IEMAC … André Lucas Freit… iemac… andrebatista2/ie… 2021-08-09…
##  3 28744… ""                employ… Yanitsa Dimitrova… emplo… yanito/employees  2021-08-09…
##  4 28744… "Process to crea… Cash I… semsad holic / Ca… cash-… semsad1978/cash-… 2021-08-09…
##  5 28744… "Web-app that an… Lunch … Mike / Lunch Calc… lunch… nmish2005/lunch-… 2021-08-09…
##  6 28744… ""                Trackm… srutheesh m / Tra… track… srutheesh0/track… 2021-08-09…
##  7 28744… ""                Yousse… Youssef Tarek / Y… youss… yousseftareky9/y… 2021-08-09…
##  8 28743… ""                advoca… Hung Hoang / advo… advoc… hung.hoang3/advo… 2021-08-09…
##  9 28743…  <NA>             emsage… emsagenerator / e… emsag… emsagenerator111… 2021-08-09…
## 10 28743… ""                line-s… Panuwat Assawinja… line-… tunoat/line-shar… 2021-08-09…
## 11 28743… ""                OX Com… Suwijak Woradee /… ox-co… 62160145/ox-comp… 2021-08-09…
## 12 28743… ""                test-a… Jhomar Alglen / t… test-… jhomaralglen/tes… 2021-08-09…
## 13 28743… ""                ADASAY… Mumun Dambrah / A… adasa… mumundambrah/ada… 2021-08-09…
## 14 28743… ""                oxcomp… Krorawit Seehawon… oxcom… 62160236/oxcompl… 2021-08-09…
## 15 28743… ""                Proyec… Nayely Ramirez / … proye… nayelyramirez/pr… 2021-08-09…
## 16 28743… "A fabric mod of… MC-dyn… mikenrafter / MC-… mc-dy… mikenrafter1/mc-… 2021-08-09…
## 17 28743… ""                userCr… Panteon_Leaderboa… userc… panteon_leaderbo… 2021-08-09…
## 18 28743… ""                intera… swissbib / swissc… inter… swissbib/swissco… 2021-08-09…
## 19 28743… "formative11"     format… Deanu Haratinu Tu… forma… deanuharatinu/fo… 2021-08-09…
## 20 28743… ""                server  Panteon_Leaderboa… server panteon_leaderbo… 2021-08-09…
## # … with 113 more variables: default_branch <chr>, ssh_url_to_repo <chr>,
## #   http_url_to_repo <chr>, web_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>, forked_from_project.id <chr>,
## #   forked_from_project.description <chr>, forked_from_project.name <chr>,
## #   forked_from_project.name_with_namespace <chr>, forked_from_project.path <chr>,
## #   forked_from_project.path_with_namespace <chr>, forked_from_project.created_at <chr>,
## #   forked_from_project.default_branch <chr>, forked_from_project.ssh_url_to_repo <chr>,
## #   forked_from_project.http_url_to_repo <chr>, …

Travailler avec un projet GitLab précis

• Explorez l’un de vos projets. Vous pouvez définir le nom du projet ou son ID. L’ID est fortement recommandé, en particulier si votre projet n’apparaît pas dans les premières pages de projets ci-dessus.
  • Explorons le projet nommé “repo.rtask”, avec ID = 20384533 sur GitLab.com

my_project <- 20384533 #repo.rtask",

• Si la branche par défaut n’est pas nommée main, vous devez le spécifier avec gitlabr_options_set().

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

• Lister les fichiers du projet avec 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

• Lister les issues/tickets avec 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>

Configurer GitLab CI avec {gitlabr} pour les packages R ou bookdown

{gitlabr} peut être utilisé pour créer un fichier .gitlab-ci.yml pour tester, construire et vérifier un package R, un bookdown, … en utilisant l’Intégration Continue (CI) de GitLab. Utilisez gitlabr::use_gitlab_ci() avec un type spécifique dans votre projet et votre CI devrait être prêt à démarrer lors du prochain commit.

Il existe des modèles prédéfinis :

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

Changements multiples depuis la dernière version

J’ai repris le développement de {gitlabr} pour qu’il continue d’être accessible sur CRAN.
Grâce aux commentaires constructifs de Robert M Flight et Jenny Brian, et aux contributions importantes de LDalby et Kevin Cazelles, nous avons un package renouvelé avec une documentation cohérente.
Les vignettes sont encore un travail en cours, et vous êtes tous les bienvenus pour participer, mais l’idée générale est définie.

Quelques changements qui ont été apportés peuvent empêcher vos anciens flux de travail de fonctionner.
Le plus important de ces changements est bien sûr le logo !

“Breaking changes”

• La branche par défaut est nommée main lorsque cela est nécessaire.
  • Cela peut être modifié avec gitlabr_options_set("gitlabr.main", "master").
• Toutes les fonctions spécifiques au projet reçoivent project comme premier paramètre. Cela implique des changements pour :
  • 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()
• Changement de api_version = "v4" pour api_version = 4
• Changement de force_api_v3 = TRUE pour api_version = 4 pour que la v3 soit obsolète par défaut.

Changements majeurs

• Nouvelle utilisation de use_gitlab_ci() avec des modèles prédéfinis
• Ajout de nouvelles fonctions pour gérer les projets : gl_get_projet(), gl_new_projet(), gl_edit_projet(),
  gl_delete_project()
• Mise à jour de la documentation : recommandation d’utiliser les fonctions gl_*.

Changements mineurs

• gl_archive() est utilisé pour archiver un projet (pas pour télécharger une archive)
• Correction de l’utilisation de max_page avec les fonctions gl_() appelant gitlab().
• Correction de l’API qui téléchargeait deux fois la première page lorsque page == "all".
• Réduire max_page dans les exemples et les tests pour récupérer le contenu afin de permettre de travailler avec de gros serveurs GitLab comme Gitlab.com
• Changement de mainteneur
• Mise à jour de CONTRIBUTING pour les tests avec Gitlab.com

Pour aller plus loin

• Tous les exemples reproductibles et la documentation de {gitlabr} se trouve dans le site pkgdown: 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
• Il y a quelques temps, j’ai rédigé: “Télécharger les issues Gitlab ou Github et faire un rapport résumé de vos commits”. Ça utilise {gitlabr} et {gitdown}.
• Notre « Guide de développement collaboratif avec R pour une publication reproductible PROPRE repose fortement sur les capacités de GitLab. {gitlabr} sera un allié pour mettre en place vos projets avec des trames similaires.