npm package: @itentialopensource/gitlab-get-diff-of-merge
Description: Default artifact description
Author: Itential Artifacts
Latest version: 0.0.6

# Gitlab Get Diff of Merge Requests 

## Table of Contents

- [Gitlab Get Diff of Merge Requests](#gitlab-get-diff-of-merge-request)
  - [Table of Contents](#table-of-contents)
  - [Overview](#overview)
  - [Supported IAP Versions](#supported-iap-versions)
  - [Getting Started](#getting-started)
    - [Prerequisites](#prerequisites)
    - [Capabilities](#capabilities)
    - [How to Install](#how-to-install)
    - [Testing](#testing)
  - [Using this Pre-Built](#using-this-pre-built)
    - [Input Schema](#input-schema)
    - [Output Schema](#output-schema)
  - [Additional Information](#additional-information)
    - [Helpful Links](#helpful-links)

## Overview

The **Gitlab Get Diff of Merge** pre-built consists of an Operations Manager automation which can be used to get the diff (difference) between the current state and the proposed changes of your gitlab project branch.

The **Gitlab Get Diff of Merge** workflow serves as an entry point for Operations Manager automation to run the use cases described above.

## Supported IAP Versions
Itential pre-builts are built and tested on particular versions of IAP. In addition, pre-builts that work with devices are often dependent on certain orchestration systems (e.g. NSO and IAG). As such, these pre-builts will have dependencies on these other systems. This version of the Gitlab get diff of merge from Repo pre-built has been tested with:

  - IAP 2023.1.x

## Getting Started

These instructions will help you get a copy of the pre-built in your IAP instance for testing in your environment. Reading this section is also helpful for deployments as it provides you with pertinent information on prerequisites and capabilities.

### Prerequisites

Users must satisfy the following prerequisites to install and run this pre-built:

- Itential Automation Platform
  - `^2023.1.x`

### Capabilities

* get you the list of changes made ona branch using a specific merege request id. 
* Select either verbose or non-verbose options in the input JSON Form for viewing the details.

### How to Install

To install the Pre-Built:

* Verify you are running a supported version of the Itential Automation Platform (IAP) as listed above in the [Prerequisites](#prerequisites) section in order to install the Pre-Built. 
* The Pre-Built can be installed from within App-Admin_Essential. Simply search for the name of your desired Pre-Built and click the install button (as shown below).

<table><tr><td>
  <img src="./images/install.png" alt="install" width="600px">
</td></tr></table>

### Testing

While Itential tests this pre-built and its capabilities, it is often the case the customer environments offer their own unique circumstances. Therefore, it is our recommendation that you deploy this pre-built into a development/testing environment in which you can test the pre-built.

## Using this Pre-Built

The main requirements to use this Pre-built are:
1. Running instance of the Itential OpenSource `adapter-gitlab`, which can be found in [adapter-gitlab](https://gitlab.com/itentialopensource/adapters/devops-netops/adapter-gitlab)

The pre-built can be run using **Operations Manager** automation **Gitlab Get Diff of Merge** Automation. Use the following steps to complete the form:

1. Select the appropriate adapter-gitlab instance from the dropdown.
2. Input the Project ID of the project.
3. Input the Merge Request ID.
4. Select either verbose or non-verbose option for the performed operation details.

> **Note:** All fields are mandatory.

### Input Schema

Example input formData:
```
{
  "formData": {
    "mergeRequestId": 10,
    "options": {
      "verbose": false
    },
    "gitLabAdapterName": "gitlab",
    "projectId": "3434"
  }
}
```

The following table details the property keys of the input object.

| key                       | type    | required | description          |
|---------------------------|---------|----------|----------------------|
| formData.projectId        | string  | yes      | project id           |
| formData.meregeRequestID  | number  | yes      | Merege Request ID    |
| formData.gitlabAdapter    | string  | yes      | adapter id           |
| formData.options          | object  | yes      | additional options   |
| formData.options.verbose  | boolean | yes      | verbose              |

### Output Schema

The ReturnStatus job variable returned from the run automation `Gitlab Get Diff of Merge Automation` reports the success or failure of the operation performed. 

Example output of successful pull operation:
```
 {
   "ReturnStatus":
    {
    "status": "SUCCESS",
    "message": "Diff found",
    "errors": [],
    "response": {
      "get a project": {
        "icode": "AD.200",
        "response": {
          "pathParam": "gitlab_gp",
          "tagList": [],
          "issues_enabled": true,
          "merge_requests_enabled": true,
          "wiki_enabled": true
          "permissions": {
            "project_access": null,
            "group_access": {
              "access_level": 50,
              "notification_level": 3
            }
          }
        },
        "headers": {
          "date": "Tue, 25 Apr 2023 19:17:17 GMT",
          "content-type": "application/json",
          "transfer-encoding": "chunked"
        },
        "metrics": {
          "code": 200,
          "timeouts": 0,
          "redirects": 0,
          "retries": 0
        }
      },
      "get diff for a specific committ": {
        "icode": "AD.200",
        "response": [
          {
            "old_path": "newfile",
            "new_path": "newfile",
            "a_mode": "0",
            "b_mode": "100644",
            "new_file": true,
            "renamed_file": false,
            "deleted_file": false,
            "diff": "@@ -0,0 +1 @@\n+This content is for creating new file\n\\ No newline at end of file\n"
          }
        ],
        "headers": {
          "date": "Tue, 25 Apr 2023 19:17:23 GMT",
          "content-type": "application/json",
          "content-length": "229"
        },
        "metrics": {
          "code": 200,
          "timeouts": 0,
          "redirects": 0,
          "retries": 0,
          "tripTime": 1439
        }
      }
    },
    "mergeRequestId": 10
  }
}
```

The following table details the property keys of the output object.

| key                                      | type   | description               |
|------------------------------------------|--------|---------------------------|
| ReturnStatus                             | object | job variable              |
| ReturnStatus.response                    | object | response                  |
| ReturnStatus.response.get diff for a specific committ    | object | operation details         |
| ReturnStatus.status                      | string | status                    |
| ReturnStatus.message                     | string | operation message         |
| ReturnStatus.mergeRequestId                  | string | mergeRequestId                |
| ReturnStatus.errors                      | array  | error details and message |
| ReturnStatus.errors.error_details        | object | error details             |
| ReturnStatus.errors.message              | string | error message             |

#### Success Example 1 - Successful Gitlab Pull file Operation
Example input for a successful pull file operation:

```
{
  "formData": {
    "mergeRequestId": 10,
    "options": {
      "verbose": false
    },
    "gitLabAdapterName": "gitlab",
    "projectId": "3434"
  }
}
```

Example output for successful pull operation:
```
 {
   "ReturnStatus":
    {
    "status": "SUCCESS",
    "message": "Diff found",
    "errors": [],
    "response": {
      "get a project": {
        "icode": "AD.200",
        "response": {
          "pathParam": "gitlab_gp",
          "tagList": [],
          "issues_enabled": true,
          "merge_requests_enabled": true,
          "wiki_enabled": true
          "permissions": {
            "project_access": null,
            "group_access": {
              "access_level": 50,
              "notification_level": 3
            }
          }
        }
      },
      "get diff for a specific committ": {
        "icode": "AD.200",
        "response": [
          {
            "old_path": "newfile",
            "new_path": "newfile",
            "a_mode": "0",
            "b_mode": "100644",
            "new_file": true,
            "renamed_file": false,
            "deleted_file": false,
            "diff": "@@ -0,0 +1 @@\n+This content is for creating new file\n\\ No newline at end of file\n"
          }
        ]
      }
    },
    "mergeRequestId": 10
  }
}
```



#### Failure Example 1 - File name doesn't Exists

Input:
```
{
  "formData": {
    "mergeRequestId": 100,
    "options": {
      "verbose": false
    },
    "gitLabAdapterName": "gitlab",
    "projectId": "3434"
  }
}
```

Output:
```
ReturnStatus:
        {
  "status": "FAILED",
  "message": "merge id not found",
  "errors": [
    {
      "error_details": {
        "icode": "AD.500",
        "IAPerror": {
          "origin": "gitlab-connectorRest-handleEndResponse",
          "displayString": "Error 404 received on request",
          "recommendation": "Verify the request is accurate via debug logs and postman",
          "code": 404,
          "raw_response": {
            "status": "success",
            "code": 404,
            "headers": {
            },
            "response": "{\"message\":\"404 Not found\"}",
          }
        },
        "response": {
          "message": "404 Not found"
        }
      },
      "message": "merge id not found"
    }
  ],
  "response": {
    "get a project": {
      "icode": "AD.200",
      "response": {
        "pathParam": "gitlab_gp",
        "tagList": [],
        "createdAt": "2023-03-10T12:33:45.340Z",
        "id": 107,
        "description": "",
        "name": "gitlab_GP"
      }
    },
    "get merge": {
      "icode": "AD.500",
      "IAPerror": {
        "origin": "gitlab-connectorRest-handleEndResponse",
        "displayString": "Error 404 received on request",
        "recommendation": "Verify the request is accurate via debug logs and postman",
        "code": 404,
        "raw_response": {
          "status": "success",
          "code": 404
          "response": "{\"message\":\"404 Not found\"}"
        }
      },
      "metrics": {
        "code": 404,
        "timeouts": 0,
        "redirects": 0
      },
      "response": {
        "message": "404 Not found"
      }
    }
  },
  "mergeRequestId": 100
}
```

The following table details the property keys of the ReturnStatus object.

| key                                      | type   | description               |
|------------------------------------------|--------|---------------------------|
| ReturnStatus                             | object | job variable              |
| ReturnStatus.response                    | object | response                  |
| ReturnStatus.response.get mereg           | object | operation details         |
| ReturnStatus.status                      | string | status                    |
| ReturnStatus.message                     | string | operation message         |
| ReturnStatus.filename                 | string | project id                |
| ReturnStatus.errors                      | array  | error details and message |
| ReturnStatus.errors.error_details        | object | error details             |
| ReturnStatus.errors.message              | string | error message             |

## Additional Information
Please use your Itential Customer Success account if you need support when using this pre-built.

### Helpful Links:
* GitLab Wikipedia: https://en.wikipedia.org/wiki/GitLab  
* GitLab Adapter: https://gitlab.com/itentialopensource/adapters/devops-netops/adapter-gitlab
* GitLab Homepage: https://gitlab.com/