Haskell library for the GitLab API

Posted on February 1, 2020

GitLab has a REST web API. It returns JSON strings.

The gitlab-haskell library lifts the GitLab API into Haskell. Rather than working with JSON strings, gitlab-haskell parses GitLab API results into Haskell types e.g. when querying branches, the type you'll be working with is:

data Branch =
  Branch
  { branch_name :: Text
  , merged :: Bool
  , protected :: Bool
  , branch_default :: Bool
  , developers_can_push :: Bool
  , developers_can_merge :: Bool
  , can_push :: Bool
  , branch_commit :: Commit
  }

Other GitLab types include Member, Owner, Permissions, Project, User, Milestone, Issue, Pipeline, Commit, Diff, Repository, Job, Group, RepositoryFile and MergeRequest. The documentation for all GitLab types is on hackage.

The Haskell API

Running GitLab actions

GitLab actions are executed using the runGitLab function:

runGitLab
  => GitLabServerConfig -- ^ the GitLab server details
  -> GitLab a           -- ^ the GitLab action
  -> IO a

Internally, this creates a single connection manager, whichs keeps track of open connections for keep-alive and is shared between multiple concurrent requests required to execute the GitLab action.

A simple example is to get all forks of a given project with a name:

projectForks :: Text -> GitLab [Project]

Use runGitLab with projectForks to obtain all forks:

forks <- runGitLab
     (defaultGitLabServer
         { url = "https://gitlab.example.com"
         , token="my_token"} )
     (projectForks "joebloggs/myproject")

The API

Some more examples of the gitlab-haskell API are:

-- projects.
allProjects         :: GitLab [Project] 
projectsWithName    :: Text -> GitLab [Project]
userProjects        :: User -> GitLab (Maybe [Project]) 
projectOfIssue      :: Issue -> GitLab Project
projectCISuccess    :: Project -> GitLab Bool
projectDiffs        :: Project -> Text -> GitLab [Diff]

-- branches.
branches            :: Project -> GitLab [Branch]

-- commits.
projectCommits      :: Project -> GitLab [Commit]

-- groups.
addUserToGroup      :: Text -> AccessLevel -> User -> GitLab (Either Status Member)

-- issues.
projectOpenedIssues :: Project -> GitLab [Issue]
userIssues          :: User -> GitLab [Issue]

-- merge requests.
mergeRequests       :: Project -> GitLab [MergeRequest]
acceptMergeRequest  :: Project -> Int -> GitLab (Either Status MergeRequest)

-- repository files.
repositoryFiles     :: Project -> FilePath -> Text -> GitLab (Maybe RepositoryFile)

The complete API is documented on hackage: http://hackage.haskell.org/package/gitlab-haskell

If you have issues using gitlab-haskell or find bugs, please report them here: https://gitlab.com/robstewart57/gitlab-haskell