# GitLab

![](https://762006384-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MJXOXEifAmpyvNVL1to%2F-MkdG6FEOq6NQs-V7faS%2F-MkdGVZHNVs_7DXooyJA%2Fgitlab-plugin-header.jpg?alt=media\&token=8473ec29-d8e7-4c89-b437-12740e205265)

## Features

* Retrieve secrets from the Keeper Vault within the GitLab Pipeline
* Set secret credentials as build arguments or environment variables
* Copy secure files from the Keeper Vault

{% hint style="info" %}
For a complete list of Keeper Secrets Manager features see the [Overview](https://docs.keeper.io/en/keeperpam/secrets-manager/overview)
{% endhint %}

## Prerequisites

This page documents the Secrets Manager GitLab integration. In order to utilize this integration, you will need:

* Keeper Secrets Manager access (See the [Quick Start Guide](https://docs.keeper.io/en/keeperpam/secrets-manager/quick-start-guide) for more details)
  * Secrets Manager addon enabled for your Keeper account
  * Membership in a Role with the Secrets Manager enforcement policy enabled
* A Keeper [Secrets Manager Application](https://docs.keeper.io/en/keeperpam/about/terminology#application) with secrets shared to it
  * See the [Quick Start Guide](https://docs.keeper.io/en/keeperpam/quick-start-guide#2.-create-an-application) for instructions on creating an Application
* An initialized Keeper [Secrets Manager Configuration](https://docs.keeper.io/en/keeperpam/secrets-manager/about/secrets-manager-configuration)
  * The GitLab integration accepts JSON and Base64 format configurations
* A GitLab account with Pipeline creation access
  * Python3 installed to the GitLab Pipeline job

## About

This action securely retrieves secrets from Keeper and places them to the desired destination of the GitLab Pipeline such as an environment variable or file.

## Setup

### Save Configuration as a Secret Variable

A keeper [Secrets Manager configuration](https://docs.keeper.io/en/keeperpam/secrets-manager/about/secrets-manager-configuration) is required to utilize the GitLab integration.

**1)** Create a Keeper Secrets Manager Configuration. See the [documentation](https://docs.keeper.io/en/keeperpam/secrets-manager/about/secrets-manager-configuration) for details. The GitLab integration supports **Base64** and **JSON** configurations.

**2)** To save the configuration in GitLab, navigate to GitLab Settings -> CI/CD -> Variables

![](https://762006384-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MJXOXEifAmpyvNVL1to%2Fuploads%2FUdGWGw0HPCgjF3kRVs77%2Fimage.png?alt=media\&token=2a244b08-0dff-4f95-9a59-8dc72927085c)

**3)** Create a new variable. Key can be set to any name for the variable (use KSM\_CONFIG to have the SDKs automatically recognize the configuration). Set Value as the Secrets Manager configuration in **Base64** or **JSON** format.

{% hint style="info" %}
Use `KSM_CONFIG` as the variable name to have Secrets Manager SDKs automatically recognize the configuration variable
{% endhint %}

![](https://762006384-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MJXOXEifAmpyvNVL1to%2Fuploads%2FYhpG7ahqgd8iL1Gqltkw%2Fimage.png?alt=media\&token=0f3c3393-4db1-4a8c-a10c-c7bb6b6a6a10)

After creating the variable, you should see it in your GitLab variables as shown below.

![](https://762006384-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MJXOXEifAmpyvNVL1to%2Fuploads%2FMoIVhziuwjV7UcqTqqmk%2Fimage.png?alt=media\&token=3668afc8-81e5-4825-aa44-e76f23e7d5ee)

{% hint style="success" %}
Keeper Secrets Manager GitLab Integration setup is complete
{% endhint %}

## Usage

### Prepare the Pipeline for Secrets Manager

In order to use Keeper Secrets Manager with GitLab, first we need to install it from the PyPi registry. This can be achieved by adding following line to the `before_script` area:

```yaml
before_script:
  - python3 -m pip install keeper-secrets-manager-cli
```

If you did not set the Secrets Manager Configuration variable to the name `KSM_CONFIG` you need to set it here in the `before_script` area

```
  - export KSM_CONFIG=$<SECRETS MANAGER CONFIG VARIABLE>
```

### Get Secrets

Inside the GitLab job, retrieve a secrets from the Keeper Vault using the following format:

```bash
$(ksm secret notation <KEEPER NOTATION>)
```

This utilizes the [KSM CLI tool](https://docs.keeper.io/en/keeperpam/secrets-manager/secrets-manager-command-line-interface) to get secrets using [Keeper Notation](https://docs.keeper.io/en/keeperpam/secrets-manager/about/keeper-notation).

After getting a secret, you can set it as an environment variable or file.

### Set Secret as Environment Variable

Use `- export <VARIABLE NAME>=$(ksm secret notation <KEEPER NOTATION>)` to set a secret to an environment variable

**Example:**

The following job sets a password secret as an environment variable named `MY_PWD` and a custom 'isbncode' record field to the environment variable named `MY _ISBNCODE`

```yaml
job1:
  stage: build
  script:
    - export MY_PWD=$(ksm secret notation keeper://XXX/field/password)
    - export MY_ISBNCODE=$(ksm secret notation keeper://XXX/custom_field/isbncode)
```

Replace `XXX` with a record UID in the above example.

{% hint style="info" %}
Keeper Secrets Manager can be used in any job stage. This example uses the `build` stage.
{% endhint %}

###

### Create a File from a Secret

Use `- ksm secret download -u <UID> --name <SECRET FILENAME> --file-output "<OUTPUT FILENAME>"` to get a file from the Keeper Vault and save it as a file to your GitLab Pipeline job.

**Example:**

The following job gets a file named "mykey.pub" that is attached to a Keeper record and saves its contents into file name "mykey.pub" in the local "tmp" folder

```yaml
job1:
  stage: build
  script:
   - ksm secret download -u XXX --name "mykey.pub" --file-output "/tmp/mykey.pub"
```

Replace `XXX` with a record UID in the above example.

{% hint style="info" %}
Keeper Secrets Manager can be used in any job stage. This example uses the `build` stage.
{% endhint %}

## Complete Example

The example below shows all available functionality of this integration

```yaml
image: python:latest

before_script:
  - python3 -m pip install keeper-secrets-manager-cli

job1:
  stage: build
  script:
    - export MY_PWD=$(ksm secret notation keeper://XXX/field/password)
    - export MY_ISBNCODE=$(ksm secret notation keeper://XXX/custom_field/isbncode)
    - ksm secret download -u XXX--name "mykey.pub" --file-output "/tmp/mykey.pub"
    - file /tmp/mykey.pub
```

Replace `XXX` in the example above with a record UID.