OCaml GitLab

GitLab is an OCaml library that allows interaction with the GitLab software hosting platform.

NOTE: This library is still under development and parts of the API might not be stable.

Installing

Source code

The source code for GitLab can be found at tmcgilchrist/ocaml-gitlab, it uses the dune build system and opam for package management.

Using opam

You can install GitLab using opam by folllowing the instructions below:

opam install gitlab

Fundamentals

GitLab allows OCaml programmers to programatically interact with the GitLab REST API. It uses two key libraries in OCaml, LWT for concurrent programming using Promises and CoHTTP to make HTTP requests. Familiarity with at least LWT is useful to understand using GitLab, in particular the Monadic interface.

To make a simple API request to find GitLab users by name:

  let open Gitlab in
  let open Monad in
  User.by_name ~name () >>~ fun users ->
  List.iter (fun user ->
    printf "%s\n" user.Gitlab_t.user_short_username) users;
    return () 

We open both the Gitlab and Monad modules to bring everything into scope, then build up a Monadic computation with User.by_name ~name and print out the users returned. Gitlab_s.Gitlab.Monad contains the expected bind, map and return functions along with infix operations like >>~ and >>=, and binding operators like let* and and*.

This expression then needs to be run in Lwt as:

let user_cmd name =
  let open Gitlab in
  let open Monad in
  User.by_name ~name () >>~ fun users ->
  List.iter (fun user ->
    printf "%s\n" user.Gitlab_t.user_short_username) users;
    return () 
in
Lwt_main.run @@ Gitlab.Monad.run (user_cmd "tmcgilchrist")

The GitLab API functions come in two flavours:

1. Simple requests that receive a single response ending with 'a Response.t Monad.t
2. Streaming paginated request that return many responses that would not fit into a single response. 'a Stream.t

For simple request use Gitlab_s.Gitlab.Monad.bind and the helper Gitlab_s.Gitlab.Monad.(>>~) from Gitlab_s.Gitlab.Monad. For streaming responses the Gitlab_s.Gitlab.Stream provides an abstraction to GitLab's paginated endpoints. For a more detailed example using the API look at the lab command line tool.

See Gitlab_s.Gitlab for the generalised GitLab API.

The GitLab API types are in Gitlab_t, users of the library would typically use these types over those in Gitlab_j.

The GitLab API types again and serialisation code for the API are in Gitlab_j, it contains duplicate type definitions from Gitlab_t and is useful if access to serialisation functions is required. Typically used for debugging or formatted output as JSON.

Gitlab_core provides the portable Functor to the GitLab API. Users of the library will not typically need this unless they want to provide another Lwt runtime eg Mirage or Javascript.

GitLab API

Full GitLab API:

• Gitlab_s
• Gitlab_core Portable functor to the GitLab API.
• Gitlab_t
• Gitlab_j

Resources

The REST API for Gitlab is available at https://docs.gitlab.com/ee/api/api_resources.html.

Bugs

Please file any issues encountered at https://github.com/tmcgilchrist/ocaml-gitlab/issues