npm package: @itentialopensource/gitlab-pull-a-file-from-repo
Description: [Deprecated] Default artifact description
Author: Itential Artifacts
Latest version: 1.0.2-2022.1.4

<!-- 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)

# Gitlab Pull A File From Repository

## Table of Contents

- [Gitlab Pull A File From Repository](#gitlab-pull-a-file-from-repository)
  - [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 Pull A File from Repository** pre-built consists of an Operations Manager automation which can be used to read an existing file from a specific gitlab project.

The **GitLab Pull a File** 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 Pull file from Repo 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

- Pulls an existing file content from gitlab repository

### 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.

### 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 Pull a file from Repo** 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 Branch Name to pull the file.
4. Input the file path.
5. Select either verbose or non-verbose option for the performed operation details.

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

### Input Schema

Example input formData:

```json
{
  "formData": {
    "gitlabAdapterName": "gitlab",
    "projectId": "3434",
    "filePath": "test",
    "gitlabBranchName": "main"
  }
}
```

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.filePath         | string  | yes      | file name            |
| formData.gitlabAdapter    | string  | yes      | adapter id           |

### Output Schema

Example output of successful pull operation:

```json
{
  "fileContents": "file text"
}
```

## 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/