npm package: @itentialopensource/create-gitlab-branch
Description: [Deprecated] Default artifact description
Author: Itential Artifacts
Latest version: 1.0.5-2023.1.3

<!-- This is a comment in md (Markdown) format, it will not be visible to the end user -->
## _Deprecation Notice_
This Pre-Built has been deprecated as of 04-15-2024 and will be end of life on 04-15-2025. The capabilities of this Pre-Built have been replaced by the [GitLab - REST](https://gitlab.com/itentialopensource/pre-built-automations/gitlab-rest)

# Create GitLab Branch

## Table of Contents

- [Create GitLab Branch](#create-gitlab-branch)
  - [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 **Create GitLab Branch** pre-built consists of an Operations Manager automation which can be used to create a branch in a GitLab project if it doesn't already exists.

The **Create GitLab Branch** 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 Create Gitlab Branch 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

* Performs the create branch operation if the branch does not exist in the specified project. 
* Input the reference branch as main, master etc depending upon the project.
* 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.

### 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 **Create GitLab Branch 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 to perform the create branch operation.
3. Input the desired **Branch Name** to perform the create branch operation.
4. If the project repository is empty the "Create Branch" Operation will throw an error. 
5. Select either verbose or non-verbose option for the performed operation details.

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

### Input Schema

Example input formData:
```
{
    "formData": {
      "options": {
        "verbose": false
      },
      "gitlabAdapter": "gitlab",
      "referenceBranch": "main",
      "projectId": "108",
      "branchName": "master-update1"
    }
}
```

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

| key                       | type    | required | description          |
|---------------------------|---------|----------|----------------------|
| formData.projectId        | string  | yes      | project id           |
| formData.branchName       | string  | yes      | branch name          |
| formData.referenceBranch  | string  | yes      | reference branch     |
| 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 `Create GitLab Branch Automation` reports the success or failure of the create operation performed.

Example output of successful create project operation:
```
    "ReturnStatus": {
      "status": "SUCCESS",
      "message": "Branch Created Successfully",
      "errors": [],
      "response": {
        "create_branch": {
          "icode": "AD.201",
          "response": {
            "name": "master-update1",
            "commit": {
              "created_at": "2023-04-04T21:38:38.000+00:00",
              "parent_ids": [],
              "title": "Initial commit",
              "message": "Initial commit",
              "author_name": "Administrator",
              "author_email": "admin@example.com",
              "authored_date": "2023-04-04T21:38:38.000+00:00",
              "committer_name": "Administrator",
              "committer_email": "admin@example.com",
              "committed_date": "2023-04-04T21:38:38.000+00:00",
              "trailers": {},
            },
          },
          "headers": {
          },
          "metrics": {
            "code": 201,
            "timeouts": 0,
          }
        }
      },
      "project_id": "108"
    }
```

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

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

#### Success Example 1 - Successful Create Branch Operation

Example input for a successful create operation:
```
{
    "formData": {
      "options": {
        "verbose": false
      },
      "gitlabAdapter": "gitlab",
      "referenceBranch": "main",
      "projectId": "108",
      "branchName": "master-update1"
    }
}
```

Example output for successful create operation:
```
    "ReturnStatus": {
      "status": "SUCCESS",
      "message": "Branch Created Successfully",
      "errors": [],
      "response": {
        "create_branch": {
          "icode": "AD.201",
          "response": {
            "name": "master-update1",
            "commit": {
              "created_at": "2023-04-04T21:38:38.000+00:00",
              "parent_ids": [],
              "title": "Initial commit",
              "message": "Initial commit",
              "author_name": "Administrator",
              "author_email": "admin@example.com",
              "authored_date": "2023-04-04T21:38:38.000+00:00",
              "committer_name": "Administrator",
              "committer_email": "admin@example.com",
              "committed_date": "2023-04-04T21:38:38.000+00:00",
              "trailers": {},
            },
          },
          "headers": {
          },
          "metrics": {
            "code": 201,
            "timeouts": 0,
          }
        }
      },
      "project_id": "108"
    }
```

#### Success Example 2 - Branch Already Exists 

This example has the key template group id value as 56922777 which is not a valid template group id which causes the pre-built to throw an error.

Input:
```
{
    "formData": {
      "options": {
        "verbose": false
      },
      "gitlabAdapter": "gitlab",
      "projectId": "108",
      "branchName": "master-update1",
      "referenceBranch": "main"
      }   
}
```

Output:
```
    "ReturnStatus": {
      "status": "SUCCESS",
      "message": "Branch Already Exists",
      "errors": [],
      "response": {
        "get_branch": {
          "icode": "AD.200",
          "response": {
            "name": "master-update1",
            "commit": {
              "id": "102c39042e9332465908ec8b04ecd6a130a9998b",
              "short_id": "102c3904",
              "created_at": "2023-04-04T21:38:38.000+00:00",
              "title": "Initial commit",
              "message": "Initial commit",
              "author_name": "Administrator",
              "author_email": "admin@example.com",
              "committer_name": "Administrator",
              "committer_email": "admin@example.com",
            },
          },
          "headers": {
          },
          "metrics": {
            "code": 200,
          }
        }
      },
      "project_id": "108"
    }
```

#### Failure Example - Connection Refused Error 

This is an example for the connection refused error which could be due to adapter connection issues.

Input: 
```
{
    "formData": {
      "options": {
        "verbose": false
      },
      "gitlabAdapter": "gitlab",
      "projectId": "108",
      "branchName": "master-update2",
      "referenceBranch": "main"
      }
}
```

Output:
```
    "ReturnStatus": {
      "status": "FAILED",
      "message": "Unknown Error Code Returned",
      "errors": [
        {
          "message": "Unknown Error Code Returned",
          "error_details": {
            "icode": "AD.500",
            "IAPerror": {
              "origin": "gitlab-connectorRest-handleEndResponse",
              "displayString": "Error -1 received on request",
              "recommendation": "Verify the request is accurate via debug logs and postman",
              "code": -1,
              "raw_response": {
                "status": "failure",
                "code": -1,
                "message": {
                  "errno": -111,
                  "code": "ECONNREFUSED",
                  "syscall": "connect",
                  "address": "172.20.100.62",
                  "port": 443
                }
              }
            },
            "metrics": {
              "code": -1,
            }
          }
        }
      ],
      "response": {
        "get_branch": {
          "icode": "AD.500",
          "IAPerror": {
            "origin": "gitlab-connectorRest-handleEndResponse",
            "displayString": "Error -1 received on request",
            "recommendation": "Verify the request is accurate via debug logs and postman",
            "code": -1,
            "raw_response": {
              "status": "failure",
              "code": -1,
              "message": {
                "errno": -111,
                "code": "ECONNREFUSED",
                "syscall": "connect",
                "address": "172.20.100.62",
                "port": 443
              },
            }
          },
          "metrics": {
            "code": -1,
          }
        }
      },
      "project_id": "108"
    }
```

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_branch         | object | operation details         |
| ReturnStatus.status                      | string | status                    |
| ReturnStatus.message                     | string | operation message         |
| ReturnStatus.project_id                  | 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/