Jenkins Pipeline Groovy Script - Part 1: Creating Gitlab Group

In this article, I am discussing a simple groovy functionality along with Jenkinsfile pipeline script on how to automatically create a new GitLab group or subgroup under the parent group.  In DevOps Continuous Integration(CI) and Continuous Delivery(CD), managing projects in git level is very much important and useful for version control.  These projects are organized under a specific groups to have a disciplined structure in order to handle the application deployment well via DevOps.

What Is Jenkins Groovy?

Groovy is  an object-oriented programming language like Java and has Domain Specific Language(DSL) features. Jenkins provides pipeline capabilities along with groovy DSL features for Continuous Integration(CI). So how to use Jenkins pipeline groovy script, use load keyword in Jenkinsfile to create constructor for groovy class. Using constructor or class object of that Groovy class, functions can be inherited and values are returned. In order to use Jenkins Pipeling Groovy script, in Jenkins CI server Pipeline Groovy Plugin should be installed as prerequisite.

Below is an example Jenkins pipeline script to call groovy class functions.

pipeline{
    node('slave') {
        classObject = load 'example.groovy'
        clssObject.function()
    }
}

Gitlab Restful API

Let's see what is Gitlab group and its purpose. Gitlab groups are predominantly used as a common place where all project related information is stored under specific group or subgroups.  A group may have multiple subgroups under parent group, but can have only one immediate parent group. It is depicted as below

• Parent Group
  • subgroup 1 
  • subgroup 2
    • subgroup 2.1
    • subgroup 2.2

Gitlab offers its functionality as Restful API, that can be leveraged via curl command. In this post  Gitlab Restful APIs for group has been used along with groovy script to create group.

Create Gitlab Group Using Groovy

So how to create gitab group by consuming Gitlab Restful API in Groovy script. Let's create groovy class as below with name gitlabGroup.groovy.

What is this groovy class does:

1.  Checks for parent group is present or not under which subgroup will be created
2.  Search for subgroup existence, if not creates subgroup

Thus to create new group, parent group is mandatory under which new given group will be created as subgroup.

import groovy.transform.Field

@Field grpfullpath

@Field groupName

@Field gitlabUrl

@Field gitlabToken

@NonCPS

def jsonParseData(jsonObj) {

    def slurObj=new groovy.json.JsonSlurper().parseText(jsonObj)

    return slurObj

}

// create gitlab group if not present already

def createGitLabGroup(gitlabToken, gitlabUrl, parentGroupId, groupName){

 stage('Create GitLab group'){

   script{

     def parentGroupId

     def groupName

     grpId=getSubGroupDetails(parentGroupId, groupName)

     if (grpId.equals(null)){     

     def subgrpCreate= sh script: """curl -X POST -H "PRIVATE-TOKEN: ${gitlabToken}" -H 'Content-Type: application/json' \

                 ${gitlabUrl}/groups \

                -d '{ "web_url":"${gitlabUrl}${grpfullpath}",

                      "name":"${groupName}", 

                      "path":"${groupName}", 

                      "description":"${groupName}", 

                      "visibility":"private", 

                      "request_access_enabled":"false",

                      "parent_id":${parentGroupId}}'""", returnStdout: true

      return jsonParseData(subgrpCreate).id

     }

     else{

        return grpId

     }

   }

  }

}

// get parent gitlab group information under subgroup will be created

def getParentGroupObject(){

  stage('Get Parent Details'){

        script{

          def groupdDetails=sh script: """curl --request GET --header "PRIVATE-TOKEN: ${gitlabToken}" ${gitlabUrl}groups/${gitlabGroupId}""", returnStdout: true

          return jsonParseData(groupdDetails)

        }

   }

}

// search gitlab group already exist or not

def getGitGroupObject(gitParentId){

 stage('Git Group Object'){

    script{

        def grpObj=sh script: """curl --request GET --header "PRIVATE-TOKEN: ${gitlabToken}" ${gitlabUrl}groups/${parentGroupId}/subgroups?search=${groupName}""", returnStdout: true

        return jsonParseData(grpObj)

        }

   }

 }

def getSubGroupDetails(parentGroupId, groupName){

    if (getParentGroupObject()==~/(.*)404(.*)/){

        println("group not found")

    }

    else{

        grpfullpath=getParentGroupObject().full_path+"/"+groupName

        def gitgrpdetails=getGitGroupObject(parentGroupId)

        def grpId=0

         for (i=0; i<gitgrpdetails.size(); i++){

          if ((gitgrpdetails.full_path[i]).equals(grpfullpath)){              

                   grpId=gitgrpdetails.id[i]

                   return grpId

          }

       }

    }

}

return this

Once after creating the above groovy class, use load constructor in Jenkins Pipeline script to call createGitlabGroup() by providing Gitlab  information such as gitlab token,  gitlab URL , parent group(Id) and group name as input arguments.

 pipeline{
    node('slave') {
        gitlabObj = load 'gitlabGroup.groovy'
        gitlabObj.createGitlabGroup(gitlabToken, gitlabURL, parentGroupId, groupName)
    }

Summary

Groovy provides more flexible and customized functionality that can be used widely for automation along with Jenkins CI server pipeline script. In Part 1,  we have seen how groovy script has been used to create Gitlab group automatically using Jenkinsfile. In Part 2, I will be explaining about how to add list of users to Gitlab group and grant them permission.