# Teller

<figure><img src="https://762006384-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MJXOXEifAmpyvNVL1to%2Fuploads%2FXXs3iDxSwPACWT36JH5O%2Fkeeper%2Bteller.jpg?alt=media&#x26;token=c7948170-0739-4e87-b27f-6b67130f4953" alt=""><figcaption></figcaption></figure>

## Features

* Retrieve secrets from the Keeper Vault within [Teller](https://github.com/tellerops/teller) environments
* Set secret credentials as environment variables in Teller

{% 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 Teller 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 Teller integration accepts Base64 format configurations

## Setup

### Getting a Secrets Manager configuration

Using Keeper Commander, add a new client to an application and initialize the configuration to a Base64 string. This will be the long text hash that appears after the "Initialized Config:" label.

```
My Vault> sm client add --app MyApp --config-init b64

Successfully generated Client Device
====================================

Initialized Config: eyJob3N0bmFtZSI6ICJr....OUk1ZTV1V2toRucXRsaWxqUT0ifQ==
IP Lock: Enabled
Token Expires On: 2021-10-19 15:31:31
App Access Expires on: Never
```

That value needs to be assigned to an environment variable with the name **KSM\_CONFIG**.

### Creating a Teller configuration

`teller` will pull variables from your Keeper Vault, and will populate your current working session so you can work safely and much more productively.

`teller` needs a tellerfile. This is a `.teller.yml` file that lives in your repo, or one that you point teller to with `teller -c your-conf.yml`.\
Run `teller new` and follow the wizard, pick the providers you like and it will generate a `.teller.yml` for you.

Alternatively, you can use the following minimal template:

<pre class="language-yaml"><code class="lang-yaml">project: project_name
<strong>opts:
</strong>  stage: development

providers:
  # requires a configuration in: KSM_CONFIG=base64_config
  # or file path KSM_CONFIG_FILE=ksm_config.json
  keeper_secretsmanager:
    # pull multiple key-value pairs from a single record
    # all non-empty fields are mapped by their labels,
    # if empty then by field type, and numeric suffix 1,2,...,N on duplicates
    env_sync:
      path: [recordUID]

    # use Keeper Notation to select individual field values
    # https://docs.keeper.io/secrets-manager/secrets-manage
    env:
      USER:
        path: [recordUID]/field/login
      PSWD:
        path: [recordUID]/field/password
</code></pre>

## Running from command line

With a `.teller.yml` file in the current directory, or one that you point teller to with `teller -c your-conf.yml`now you can just run processes with:.

```bash
$ teller run node src/server.js
Service is up.
Loaded configuration: Mailgun, SMTP
Port: 5050
```

## Using a GitHub Action

Add a teller step.

```yaml
# set up teller step
- name: Setup Teller
  uses: spectralops/setup-teller@v2
- name: Run a Teller task (show, scan, run, etc.)
  run: teller run [args]
```

Full example below is using the default config file `.teller.yml` which can be replaced in the `run` command with a custom file that you point teller to with `teller -c your-conf.yml`.

```yaml
name: run with teller
on:
  push:
    branches:
      - master
      - main
  pull_request:

jobs:
  build:
    name: Build your code
    runs-on: ubuntu-latest

    steps:
      - name: Clone repo
        uses: actions/checkout@master


      # set up teller
      - name: Setup Teller
        uses: spectralops/setup-teller@v2

      - name: Run a Teller task (show, scan, run, etc.)
        run: teller run npm run build
```