@itentialopensource/create-project v2.0.3-2022.1.2

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 Project

Table of Contents

• Create GitLab Project
  • 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 Project pre-built consists of an Operations Manager automation which can be used to create a project in GitLab if it doesn't already exists, with or without using a custom template.

The Create GitLab Project workflow serves as an entry point for Operations Manager automation to run the use cases described above. The running path of the workflow depends on the operation selected by the user. The user is provided with an option to select either "Creating Project With Template" or "Creating Project Without Template" trigger and use the JSON form to input data.

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 Project pre-built has been tested with:

• IAP 2022.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
  • ^2022.1.x

Capabilities

• Performs the create project operation if the project does not exist in the specified group ID.
• Select either create project with template or create project without template option in the automation to get corresponding JSON forms to input the data.
• If Template Name is not provided or does not exist in the Template GroupID - Dropdown to select the template to use for the new project in the specified Template GroupID.
• 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 Project Automation. Use the following steps to complete the form:

1. Select the appropriate manual trigger to either "Create Project With Template" or "Create Project Without Template".
2. Select the appropriate adapter-gitlab instance from the dropdown.
3. Input the Group ID of the group that is needed to perform the create project operation. The new project will be created inside the specified Group ID.
4. Input the desired New Project Name and Project Description to perform the create operation.
5. If "Create Project With Template" trigger is selected. Enter the Template Group Id and optionally enter the Template Name to select the template for the new project.
6. If Template Name is not provided or is not a match to what's available, a form work task will let you choose from the templates that are available in the Template Group Id specified in the form.
7. Select either verbose or non-verbose option for the performed operation details.

Requires: New Project Name, Project Description, Group Id, Template Name and Template Group Id.

Note: All fields are mandatory for the "Create Project With Template" form except for the Template Name. For the "Create Project without Template" all fields are mandatory.

Input Schema

Example input formData:

{
    "formData": {
      "options": {
        "verbose": false
      },
      "gitlabAdapterName": "gitlab",
      "groupId": "65990124",
      "newProjectName": "Create a Project Using Prebuilt Template Via IAP",
      "projectDescription": "Create a Project Using Prebuilt Template Via IAP",
      "templateGroupId": "56922778",
      "templateName": "Inventory Report Template"
    }
}

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

Output Schema

The ReturnStatus job variable returned from the run automation Create GitLab Project Automation reports the success or failure of the create operation performed.

Example output of successful create project operation:

    "ReturnStatus": {
      "status": "SUCCESS",
      "message": "Project Created Successfully",
      "errors": [],
      "response": {
        "create_new_project": {
          "icode": "AD.201",
          "response": {
            "pathParam": "create-a-project-using-prebuilt-template-via-iap",
            "createdAt": "2023-04-19T17:19:38.388Z",
            "id": 45319156,
            "description": "Create a Project Using Prebuilt Template Via IAP Test",
            "name": "Create a Project Using Prebuilt Template Via IAP Test",
            "last_activity_at": "2023-04-19T17:19:38.388Z",
            "archived": false
          },
          "headers": {
            "date": "Wed, 19 Apr 2023 17:19:40 GMT",
          },
          "metrics": {
            "code": 201,
          }
        }
      },
      "group_id": "65990124",
      "template_id": "56922778",
      "project_id": 45319156
    }

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

Success Example - Successful Create Project With Template Operation

Example input for a successful create operation:

{
    "formData": {
      "options": {
        "verbose": false
      },
      "gitlabAdapterName": "gitlab",
      "groupId": "65990124",
      "newProjectName": "Create a Project Using Prebuilt Template Via IAP Test",
      "projectDescription": "Create a Project Using Prebuilt Template Via IAP Test",
      "templateGroupId": "56922778",
      "templateName": "Inventory Report Template"
    }
}

Example output for successful create operation:

    "ReturnStatus": {
      "status": "SUCCESS",
      "message": "Project Created Successfully",
      "errors": [],
      "response": {
        "create_new_project": {
          "icode": "AD.201",
          "response": {
            "createdAt": "2023-04-19T17:19:38.388Z",
            "id": 45319156,
            "description": "Create a Project Using Prebuilt Template Via IAP Test",
            "name": "Create a Project Using Prebuilt Template Via IAP Test",
          },
          "headers": {
            "date": "Wed, 19 Apr 2023 17:19:40 GMT",
          },
          "metrics": {
            "code": 201,
            "timeouts": 0,
          }
        }
      },
      "group_id": "65990124",
      "template_id": "56922778",
      "project_id": 45319156
    }

Failure Example 1 - Invalid Template Group ID

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
      },
      "gitlabAdapterName": "gitlab",
      "groupId": "65990124",
      "newProjectName": "Create a Project Using Prebuilt Template Via IAP 2",
      "projectDescription": "Create a Project Using Prebuilt Template Via IAP 2",
      "templateGroupId": "56922777"
    }
}      

Output:

    "ReturnStatus": {
      "status": "FAILED",
      "message": "Get list of templates task failed.",
      "errors": [
        {
          "message": "Get list of templates task failed.",
          "error_details": {
            "icode": "AD.500",
            "IAPerror": {
              "origin": "Gitlab for Tools-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": {
                  "date": "Wed, 19 Apr 2023 18:42:03 GMT",
                  "content-type": "application/json",
                },
                "response": "{\"message\":\"404 Group Not Found\"}",
              }
            },
            "metrics": {
              "code": 404,
            },
            "response": {
              "message": "404 Group Not Found"
            }
          }
        }
      ],
      "response": {
        "get_list_of_templates": {
          "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 Group Not Found\"}",
              }
            }
          }
        }
      },
      "group_id": "65990124",
      "template_id": "56922777"
    }

Failure Example 2 - 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
      },
      "gitlabAdapterName": "gitlab",
      "groupId": "133",
      "newProjectName": "Create a Project Using Prebuilt Template Via IAP 3",
      "projectDescription": "Create a Project Using Prebuilt Template Via IAP 3"
      }
}

Output:

    "ReturnStatus": {
      "status": "FAILED",
      "message": "Error getting the list of projects in the group.",
      "errors": [
        {
          "message": "Error getting the list of projects in the group.",
          "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_list_of_projects": {
          "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,
            }
          },
          "metrics": {
            "code": -1,
          }
        }
      },
      "group_id": "133"
    }

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/