npm package: @itentialopensource/automation-gateway-copy-file-from-gitlab
Description: Copies a file from a GitLab repository to an IAG server
Author: Itential Artifacts
Latest version: 0.0.9-2023.1.0

<!-- This is a comment in md (Markdown) format, it will not be visible to the end user -->

<!-- Update the below line with your artifact name -->
# Automation Gateway Copy File from Gitlab

<!-- Leave TOC intact unless you've added or removed headers -->
## Table of Contents

* [Overview](#overview)
* [Installation Prerequisites](#installation-prerequisites)
* [Requirements](#requirements)
* [Features](#features)
* [How to Install](#how-to-install)
* [How to Run](#how-to-run)
* [Additional Information](#additional-information)

## Overview

<table><tr><td>
<img  src="./images/automation-studio.png"  alt="Automation Studio"  width="600px">
</td></tr></table>

This Pre-Built Automation enables users to copy a file from a Gitlab repository to an IAG server.

_Estimated Run Time_: 0 min.

## Installation Prerequisites

Users must satisfy the following pre-requisites:

    Itential Automation Platform

    2022.1

Create an authentication token in Gitlab to put into the Gitlab adapter configuration.

Sample Gitlab adapter configuration:
```
{
    "name": "gitlab",
    "model": "@itentialopensource/adapter-gitlab",
    "type": "Adapter",
    "properties": {
        "id": "gitlab",
        "type": "Gitlab",
        "properties": {
            "host": "gitlab.com",
            "port": 443,
            "base_path": "/api",
            "version": "v4",
            "cache_location": "local",
            "save_metric": true,
            "stub": false,
            "protocol": "https",
            "authentication": {
                "auth_method": "static_token",
                "username": "",
                "password": "",
                "auth_field": "header.headers.Private-Token",
                "auth_field_format": "{token}",
                "token": "************************",
                "invalid_token_error": 401,
                "token_timeout": 0,
                "token_cache": "local"
            },
            "healthcheck": {
                "type": "startup",
                "frequency": 300000
            },
            "request": {
                "number_retries": 3,
                "limit_retry_error": 401,
                "failover_codes": [
                    404,
                    405
                ],
                "attempt_timeout": 5000,
                "global_request": {
                    "payload": {},
                    "uriOptions": {},
                    "addlHeaders": {},
                    "authData": {}
                },
                "healthcheck_on_timeout": false,
                "return_raw": false,
                "archiving": false
            },
            "ssl": {
                "ecdhCurve": "",
                "enabled": false,
                "accept_invalid_cert": false,
                "ca_file": "",
                "secure_protocol": "",
                "ciphers": ""
            },
            "throttle": {
                "throttle_enabled": false,
                "number_pronghorns": 1,
                "sync_async": "sync",
                "max_in_queue": 1000,
                "concurrent_max": 1,
                "expire_timeout": 0,
                "avg_runtime": 200
            },
            "proxy": {
                "enabled": false,
                "host": "localhost",
                "port": 9999,
                "protocol": "http"
            },
            "mongo": {
                "host": "",
                "port": 0,
                "database": "",
                "username": "",
                "password": ""
            }
        },
        "brokers": [],
        "groups": []
    },
    "isEncrypted": false,
    "loggerProps": {
        "description": "Logging",
        "log_max_files": 100,
        "log_max_file_size": 1048576,
        "log_level": "info",
        "log_directory": "./logs",
        "log_filename": "pronghorn.log",
        "console_level": "info"    
        }
}
```

Copy this helper script to the destination IAG server and customize it for the environment.  Name it "import_playbook.pl" and make it executable and make sure it is in a path that is configured as a script path in properties.yml for the IAG server.

```
#!/usr/bin/perl

use MIME::Base64;

# NOTE: adjust this to a path in the configured playbook paths in properties.yml
my $basePath = "/usr/share/ansible/playbooks/";
my $filename = $ARGV[0];
my $content = $ARGV[1];

my $fullfile = $basePath . $filename;

my $decoded = decode_base64(decode_base64($content));

print "Writing playbook to $fullfile\n";

open(FH, '>', $fullfile) or die	$!;
print FH $content;
close(FH);

print "Done.";

```

## Requirements

This Pre-Built requires the following:

* The Automation Gateway Adapter must be installed
* The Gitlab adapter must be installed

## Features

The main benefits and features of the Pre-Built are outlined below.

* This will copy a file from a Gitlab repository to an Itential Automation Gateway server.

## 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 [Requirements](#requirements) 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>

## How to Run

Use the following to run the Pre-Built:

Run the automation from Operations Manager, fill in the form values and select start.

Hover over the blue tool tips next to each form field for more details.
Sample form values have been provided below as an example.

<table><tr><td>
<img  src="./images/automation-catalog-example.png"  alt="Automation Catalog example"  width="600px">
</td></tr></table>

Use the Gitlab repository ID from the project you would like to copy a file from. It is located on the main page for the project under the project name. 

<table><tr><td>
<img  src="./images/gitlab-project-id.png"  alt="Gitlab Project ID location"  width="600px">
</td></tr></table>

## Additional Information

Please use your Itential Customer Success account if you need support when using this Pre-Built Transformation.