Secrets

Secrets provide a secure way to inject sensitive values — passwords, API keys, tokens — into generator configs without storing them in plain text. Values are kept in an encrypted keyring file and referenced in configs with ${secrets.name} tokens.

How it works

Secrets follow the same substitution model as parameters, but the values come from an encrypted file instead of startup.yml or the --params CLI flag:

output:
  - opensearch:
      hosts:
        - ${params.opensearch_host}
      username: ${params.opensearch_user}
      password: ${secrets.opensearch_password}   # from the keyring

When Eventum loads the config, it extracts all ${secrets.*} tokens, looks up each name in the encrypted keyring, decrypts the values, and substitutes them into the config before YAML parsing.

Renaming a secret on the Secrets page rewrites the token in every config that reads it, so the reference follows the name. The rewrite is textual — comments and formatting are left as they were.

The keyring and cryptfile

Secrets are stored in an encrypted file called the cryptfile, managed by the keyrings.cryptfile library. The cryptfile is AES-encrypted and protected by a password.

Keyring password

The keyring password is read from the EVENTUM_KEYRING_PASSWORD environment variable. If the variable is not set, Eventum falls back to the default password eventum and logs a warning.

For production use, always set a custom password:

export EVENTUM_KEYRING_PASSWORD="your-strong-password"

Cryptfile location

The cryptfile path depends on how you run Eventum:

Naming a secret

A configuration reads a secret as ${secrets.<name>} and is rendered to substitute it, so the name is read as an expression: words of lowercase letters, digits and _, separated by ., each word starting with a letter or _.

Lowercase is part of the rule rather than a convention: the keyring stores a name in a form that does not keep its case, while the value is encrypted against the name as it was given, so a name holding a capital would be listed in a spelling that cannot read it back.

A name outside that could be stored but never read back, so it is refused wherever a secret is written — the CLI, the API, Studio and the rename tool of an MCP agent. Names already in a keyring are left as they are; rename one to bring it back into use.

Managing secrets with eventum-keyring

The eventum-keyring CLI tool lets you add, read, and remove secrets from the cryptfile.

Set a secret

# Provide the value inline
eventum-keyring set db_password "s3cret"

# Or omit the value to be prompted interactively (input is hidden)
eventum-keyring set db_password
# Enter password of `db_password`: ********

Get a secret

eventum-keyring get db_password
# s3cret

Remove a secret

eventum-keyring remove db_password

Custom cryptfile location

Every subcommand accepts a --cryptfile flag to work with a specific file instead of the system default:

eventum-keyring set api_key "tok_abc123" --cryptfile ./my-project/cryptfile.cfg
eventum-keyring get api_key --cryptfile ./my-project/cryptfile.cfg

This is the same file referenced by path.keyring_cryptfile in eventum.yml or --cryptfile on eventum generate.

Using secrets in configs

Reference secrets with ${secrets.name} anywhere in generator.yml:

output:
  - http:
      url: https://api.example.com/ingest
      headers:
        Authorization: "Bearer ${secrets.api_token}"

  - opensearch:
      hosts:
        - https://opensearch.prod:9200
      username: admin
      password: ${secrets.opensearch_password}

  - clickhouse:
      host: clickhouse.prod
      username: ${secrets.ch_user}
      password: ${secrets.ch_password}

Using secrets in the repositories file

The password of a connected repository is read the same way. Written as a reference, it is resolved from the keyring every time the repository is fetched, so the token itself never enters the file:

- name: internal
  url: https://git.example.com/platform/generators.git
  username: eventum
  password: ${secrets.internal_git_token}

Missing secrets

If a config references ${secrets.name} but the secret is not in the keyring, Eventum raises an error at load time and the generator does not start:

Error: Failed to obtain secrets used in configuration
Reason: Cannot obtain secret `api_token`: Secret is missing

This prevents generators from running with empty credentials.

When to use secrets

Credentials and sensitive data — passwords for OpenSearch, ClickHouse; API keys and tokens for authentication to HTTP endpoints or any other output destination:

eventum-keyring set opensearch_password "prod-password-here"
eventum-keyring set ch_password "clickhouse-secret"
eventum-keyring set api_token "tok_abc123xyz"

output:
  - opensearch:
      password: ${secrets.opensearch_password}
  - clickhouse:
      password: ${secrets.ch_password}
  - http:
      url: https://api.example.com/events
      headers:
        Authorization: "Bearer ${secrets.api_token}"

Secrets vs parameters

For the full CLI reference see $ eventum-keyring command page.