Secret Management

Where do I store secrets?

The .env file

caution

This file should be gitignored. It is not intended to be committed to your repository.

The most common approach to managing secrets is a .env file. alto will read the .env file in the same directory as the alto.toml and use those values as environment variables. This is very useful for storing secrets that you don't want to commit to your repository because it unifies the developer and deployment experience. During production deployments, you can use any of the many tools available to manage secrets in production environments which use environment variables as a common denominator. It is also useful for Github Actions and CI workflows. The alto init command will create this file for you.

To reference environment variables in your alto.toml file, you can use the @format {env[VARIABLE_NAME]} syntax. For example, if you have a variable named MY_SECRET in your .env file or in the environment, you can reference it in your alto.toml file like this:

TOML

alto.toml

[default.taps.tap-name]
config.my_secret_key = "@format {env[MY_SECRET]}"
config.my_notsosecret_id = "12345"

YAML

alto.yaml

default:
  taps:
    tap-name:
      config:
        my_secret_key: "@format {env[MY_SECRET]}"
        my_notsosecret_id: "12345"

JSON

alto.json

{
  "default": {
    "taps": {
      "tap-name": {
        "config": {
          "my_secret_key": "@format {env[MY_SECRET]}",
          "my_notsosecret_id": "12345"
        }
      }
    }
  }
}

There is an entire section on dynamic values in the Dynaconf documentation that you can read more about here.

The alto.local.toml file

caution

This file should be gitignored. It is not intended to be committed to your repository.

Secrets can be stored in the alto.local.toml file. This file is optional. Alto will look for this file in the current directory when you run a command and merge it into alto.toml at runtime. The alto init command will create this file for you. The primary purpose of this file is to enable developer specific overrides. It lets you add entire configuration blocks such as taps, targets, or more often utilities that you want to use in your personal environment, and it can be thought of as a set of local overrides/settings. Ensure prod environments either do not rely on this file or that you have a way to inject the file into the environment at runtime. The .env / environment variable approach is a better way to manage secrets in production environments.