GitLab Integration

GitLab is a cloud-based DevOps platform that allows teams to plan work, collaborate on code development, build applications, and deploy applications. It provides various tools that cover the entire application development lifecycle. The features and functionalities provided by GitLab include version control, requirements management, project management, automated build generation, testing and release management, etc.

You can integrate GitLab with ServiceDesk Plus Cloud to implement software projects in GitLab via the change module in ServiceDesk Plus Cloud. You can also raise issues in GitLab based on the incident requests in ServiceDesk Plus Cloud.

Integrate GitLab with ServiceDesk Plus Cloud 

The integration between GitLab and ServiceDesk Plus Cloud enables the following functionalities:

• Automatically create a project in GitLab from a change request

• View GitLab project on the respective change details page

• Create an issue in GitLab from an incident request

To set up the integration, GitLab APIs are used to create scripts that can be used to configure and enable the required functionalities by creating necessary custom functions, triggers, custom module, change templates, and a custom menu.

• Step 1: Obtain Personal Access Token from GitLab
• Step 2: Create a Global Variable Using the Personal Access Token
• Step 3: Build a Functionality to Create Projects in GitLab
• Step 4: Build a Functionality to View GitLab Projects in Change Requests
• Step 5: Build a Functionality to Raise an Issue in GitLab Projects from an Incident Requests

Step 1: Obtain Personal Access Token from GitLab 

GitLab uses personal access tokens to authenticate API calls.

You can create as many personal access tokens as you like.

1. In the top-right corner, select your avatar.

2. Select Edit profile.

3. On the left sidebar, select Access Tokens.

4. Enter a name and optional expiry date for the token.

5. Select the desired scopes.

6. Select Create personal access token.

Save the personal access token somewhere safe. After you leave the page, you no longer have access to the token. 

 Step 2: Create a Global Variable Using the Personal Access Token 

To use the personal access token obtained from GitLab in custom scripts, a global variable must be created as described below:

1. Go to Setup > Developer Space > Global Variables.

2. Click New Group.

3. Provide a name and description.

4. Create the following variables and add the respective values.

5. Finally, click Save.

Note: The variable names used here should match the names used in the custom functions. If you are using the default custom function scripts, use the names mentioned in the above table.

Step 3: Build a Functionality to Create Projects in GitLab 

To automate project creation in GitLab via ServiceDesk Plus Cloud, create a custom function with GitLab APIs and invoke it in appropriate change requests via triggers.

1. Go to Setup > Developer Space > Custom Functions.

2. Click New custom function.

3. Provide a name and description for the custom function and copy the script below to the code editor. 

   Create a Project in GitLab from Change Request

   try 
   {
       change_id = changeObj.get("id");
       change_desc = changeObj.get("description");
       payload = {"name":changeObj.get("title")};
       sdp_portal_name = context.get("instance");
       if(change_desc != null)
       {
           payload.put("description",change_desc);
       }
       input_data = {"input_data":{"list_info":{"search_criteria":{"field":"name","condition":"is","value":"Gitlab"}}}};
       response = zoho.sdp.invokeurl
       [
           url :"/app/" + sdp_portal_name + "/api/v3/global_variable_groups"
           type :GET
           parameters:input_data
       ];
       global_variable_id = response.get("global_variable_groups").get(0).get("id");
       get_global_variable_group = zoho.sdp.invokeurl
       [
           url :"/app/" + sdp_portal_name + "/api/v3/global_variable_groups/" + global_variable_id
           type :GET
       ];
       variables = get_global_variable_group.get("global_variable_group").get("variables");
       personal_access_token = null;
       for each  variable in variables
       {
           if(variable.get("name") == "PersonalAccessToken")
           {
               personal_access_token = variable.get("value");
           }
       }
       response = invokeurl
       [
           url :"https://gitlab.com/api/v4/projects"
           type :POST
           parameters:payload.toString()
           headers:{"Accept":"application/json","Content-Type":"application/json","PRIVATE-TOKEN":personal_access_token}
       ];
       project_id = response.get("id");
       params = {"input_data":{"cm_gitlab_project":{"cm_attributes":{"txt_name":toString(project_id),"txt_change_id":change_id}}}};
       store_project_id = zoho.sdp.invokeurl
       [
           url :"/app/" + sdp_portal_name + "/api/v3/cm_gitlab_project"
           type :POST
           parameters:params
       ];
   }
   catch (e)
   {
       info e;
   }
   return;

4. Click, Save.

6. Go to Setup > Developer Space > Custom Modules.

7. Click New.

8. Under the Details tab, provide name and its plural form. A default API name will be generated. Click Save and go to the Fields tab.

9. Now a single-line, mandatory, unique field with name "Change Id". By default, the Gitlab Project Name field is included in the custom module.

10. Click Save.

11. Go to Setup > Automation > Triggers > Triggers for Changes.

12. Click New Trigger.

13. Provide a name and description for the change trigger.

14. Set Execute when a Change is to Edited.

15. Set Execute during to Anytime.

16. Configure the conditions when you want to create GitLab Project automatically. For example, you can configure the trigger to be applied when the change request is moved to the Implementation stage for specific change templates.

17. Select the custom function created for the trigger action.

18. Finally, click Save.

A project in GitLab will be created automatically from a change request when the conditions configured in the trigger are met. The project name will be the same as the name of the change request from which it was created.

 Step 4: Build a Functionality to View GitLab Projects in Change Requests 

You can view GitLab project in the respective change request from which it is created, by building functionality using custom widgets.  

1. Download the custom widget.

2. Go to Setup > Developer Space > Custom Widgets.

3. Click New Custom Widget.

4. Provide name and description.

5. Upload the custom widget file (.zip) downloaded from step 1.

6. Set the Hosting to Sigma Server.

7. Finally, click Save.

When a GitLab project is automatically created from a change request, a sub-tab showing the project details will be added to the configured change stage. You can customize the stage in which the tab appears by selecting your preferred stages by expanding the widget details under Setup > Developer Space > Custom Widgets. 

Sample:
 

 Step 5: Build a Functionality to Raise an Issue in GitLab Projects from an Incident Requests 

By building a functionality with custom menu, you can use ServiceDesk Plus Cloud to raise bugs in GitLab projects that were created from change requests. This functionality allows you to report bugs from incident requests that are associated with the change request used to create GitLab project.

1. Go to Setup > Developer Space > Custom Functions.

2. Click New custom function.

3. Provide a name and description for the custom function and copy the script below to the code editor. 

   Create an Issue in GitLab from Incident Requests

   try 
   {
       sdp_portal_name = context.get("instance");
       input_data = {"input_data":{"list_info":{"search_criteria":{"field":"name","condition":"is","value":"Gitlab"}}}};
       response = zoho.sdp.invokeurl
       [
           url :"/app/" + sdp_portal_name + "/api/v3/global_variable_groups"
           type :GET
           parameters:input_data
       ];
       global_variable_id = response.get("global_variable_groups").get(0).get("id");
       get_global_variable_group = zoho.sdp.invokeurl
       [
           url :"/app/" + sdp_portal_name + "/api/v3/global_variable_groups/" + global_variable_id
           type :GET
       ];
       variables = get_global_variable_group.get("global_variable_group").get("variables");
       personal_access_token = null;
       for each  variable in variables
       {
           if(variable.get("name") == "PersonalAccessToken")
           {
               personal_access_token = variable.get("value");
               break;
           }
       }
       req_id = requestObj.get("id");
       req_desc = requestObj.get("description");
       get_change_details = zoho.sdp.invokeurl
       [
           url :"/api/v3/requests/" + req_id + "/change_initiated_request"
           type :GET
       ];
       change = get_change_details.get("change_initiated_request");
       if(change == {})
       {
           return {"success":false,"message":"Please attach the change that initiated this request"};
       }
       get_project_id = zoho.sdp.invokeurl
       [
           url :"/api/v3/cm_gitlab_project"
           type :GET
           parameters:{"input_data":{"list_info":{"search_criteria":{"field":"cm_attributes.txt_change_id","value":change.get(0).get("change").get("id"),"condition":"is"},"fields_required":{"cm_attributes.txt_name"}}}}
       ];
       gitlab_project_id = get_project_id.get("cm_gitlab_project");
       if(gitlab_project_id == {})
       {
           return {"success":false,"message":"No gitlab project was created by the current associated change"};
       }
       gitlab_project_id = gitlab_project_id.get(0).get("cm_attributes").get("txt_name");
       input_data = {"title":requestObj.get("subject")};
       if(req_desc != null)
       {
           input_data.put("description",req_desc);
       }
       response = invokeurl
       [
           url :"https://gitlab.com/api/v4/projects/" + gitlab_project_id + "/issues"
           type :POST
           parameters:input_data.toString()
           headers:{"Accept":"application/json","Content-Type":"application/json","PRIVATE-TOKEN":personal_access_token}
       ];
       return {"success":true,"message":"Issue created in Gitlab Successfully"};
   }
   catch (e)
   {
       info e;
   }
   return Map();

4. Click, Save.

6. Go to Setup > Developer Space > Custom Menu > Custom Menu for Request.

7. Click Add on the top-right and click New Menu Group.

8. Provide a name and description for the menu group and set Status to Enable.

9. Click Save.

10. Click the name of the menu group created and click New Menu Item.

11. Provide a name and description for the menu item, configure necessary conditions and status, and add the custom function configured in step 4 as the action.

12. Finally, click Save.

With this configuration, an option to raise an issue in GitLab project will be available under the Custom Actions drop-down on the request details page. If an incident request is associated with a change request that is tied to a GitLab project, invoking this custom action will create an issue in the respective project; an error will be thrown in all other cases.