---
id: secrets
title: Secrets vault
sidebar_label: Secrets
---

Key/value pairs, grouped by name, encrypted at rest with AES-256-GCM under
`KEY_ENCRYPTION_KEY`. Two things consume them: workflow steps, and Kubernetes
External Secrets Operator.

## Groups and values

A **group** is a named bundle, such as `prod-db`, `registry` or `acme-api`.
Inside it are key/value pairs.

Group by who uses them rather than by what they are. A workflow step references
a whole group, so a group that matches one job stays tidy, while a group holding
everything hands all of it to every step that needs any of it.

## Managing them

**Secrets → New group**, then add keys.

Once saved, a value is hidden. The list shows key names only. **Reveal** is a
separate action, and it is written to the audit log.

Deleting a single key and deleting the whole group are separate operations.

## Using secrets in workflows

Add the group to a step's secret references. When the step runs, the group's
pairs are available to it as environment variables:

```bash
# with the "registry" group attached to this step
echo "$REGISTRY_PASSWORD" | docker login registry.example.com -u "$REGISTRY_USER" --password-stdin
```

A workflow can change which groups a step uses without changing the step in the
library.

:::warning A step can print its own secrets
Values arrive as environment variables. If your script prints them, or runs with
`set -x`, they end up in the run log, which anyone who can see the run can read.
Vantage does not filter step output.
:::

## Kubernetes External Secrets Operator

Kubernetes can read a secret group directly, using a token rather than a
sign-in.

1. Generate the token at **Settings → Integrations**. It is shown once, and
   Vantage stores only a fingerprint of it.
2. Put it in a Kubernetes secret.
3. Point an External Secrets Operator `SecretStore` at your Vantage address with
   that token.

Generating a new token replaces the old one immediately.

:::danger This token reads every group
It is instance-wide, not scoped to one group. Treat it as a credential to the
whole vault: store it as a secret in the cluster, never in a manifest in git,
and rotate it when anyone with access leaves.
:::

## What the vault is not

- **Not a password manager.** There is no sharing, expiry or per-user
  visibility. Anyone who can sign in and reveal, can reveal.
- **Not versioned.** Overwriting a value loses the previous one.
- **Not recoverable without the key.** If `KEY_ENCRYPTION_KEY` is lost, so is
  every value. Back it up separately from the database.