@itentialopensource/create-gitlab-branch v1.0.5-2023.1.3

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

Create GitLab Branch

Table of Contents

• Create GitLab Branch
  • Table of Contents
  • Overview
  • Supported IAP Versions
  • Getting Started
    • Prerequisites
    • Capabilities
    • How to Install
    • Testing
  • Using this Pre-Built
    • Input Schema
    • Output Schema
  • Additional Information
    • 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 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

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.

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.

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.

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/