acaloiaro / ess

ess (env-sample-sync): automatically and safely synchronize env.sample files with .env

ess (env sample sync)

Automatically keep env.sample files in sync with .env

---

ess transforms environment files containing secrets (e.g. .env, .envrc) into sample environment files (e.g. env.sample) that may be safely checked into git.

ess may be run manually by running the cli executable, or automatically by installing the pre-commit hook with ess install in any git repository. Installing ess as a git hook ensures that project environment files are automatically and safely revision controlled when they change.

Doing so allows environment configurations to be shared across teams without leaking secrets.

How it works

By default, ess checks the local directory for environment files named .env. The env file name is controlled by the --env-file switch. Next, the environment file is parsed for environment variables. Environment variables may be of the following forms:

# Standard environment variables
FOO=bar baz
FOO="bar baz"
FOO='bar baz'

# Envrc environment variable
export FOO=bar baz
export FOO="bar baz"
export FOO='bar baz'

By default, variable values are replaced with innert values named after the variable, e.g. FOO=bar is replaced by FOO=<FOO>.

Example values may be provided with the --example switch, e.g. --exmaple=FOO="enter your foo here" will set FOO's value as follows FOO="enter your foo here" in the sample file.

Finally, when all variables are replaced, the sample file is written with the sanitized variable values, along with all non-variable strings from the file. By default the sample file is named env.sample, which is controlled by the --env-sample switch.

Because ess permits non-variable strings in environment files, it means that both comments and script code (in the case of .envrc files) is included in environment sample files. This allows environment files to not only be checked into git, but documented with comments.

Installation & Usage

ess can be run in three ways:

1. Manually
2. As a native git-hook
3. As a pre-commit plugin (a utility for organizing pre-commit hooks)

Installation

Installation is required to run ess manually, or as a native git hook. See [pre-commit configuration] (#running-as-a-pre-commit-plugin) for pre-commit usage.

Install from the releases page

Download the latest release and add it to your $PATH.

Install with go install

go install github.com/acaloiaro/ess@latest

Nix Flake

This application may be added as a flake input

flake.nix

inputs.ess = {
  url = "github:acaloiaro/ess";
  inputs.nixpkgs.follows = "nixpkgs";
};

configuration.nix

users.users.<USERNAME>.packages = [
  ...
  inputs.ess.packages.${system}.default
];

Or simply run directly

nix run github:acaloiaro/ess

Running manually

ess can be run with no arguments to use defaults.

Sync .env with env.sample

ess

With a non-default .env and env.sample location

ess --env-file=.env-file-name --sample-file=env-sample-file-name

Provide example values for variables

By default, ess uses the name of environment variables in <brackets> as example values in env.sample, e.g. FOO=secret value is replaced with FOO=<FOO>. This behavior is customizable wit the --example flag.

Add custom examples for variables FOO and BAR.

ess --example=FOO="must be a valid UUID" --example=BAR="bars must be a positive integer"

The above invocation yields the following env.sample

FOO=must be a valid UUID

BAR=bars must be a positive integer

Running as a native git-hook

To add ess as a pre-commit git hook in a git repository, run:

ess install

This installs ess as a pre-commit git hook with default arguments.

The install command supports all command flags.

If you need to change ess flags, simply run ess install again with the desired flags and choose the overwrite [o] option when prompted what to do with the existing pre-commit hook.

Running as a pre-commit plugin

This utility can be used as a pre-commit plugin

Add configuration

cat <<EOF > .pre-commit-config.yaml
repos:
-   repo: https://github.com/acaloiaro/ess.git
    rev: v2.6.0
    hooks:
      - id: ess
EOF
pre-commit install
git add .pre-commit-config.yaml

See pre-commit configuration examples for additional pre-commit documentation.

Background

It's important to document the environment variables required to run applications, both in production and development. A great way to do so is with env.sample files, but sample files tend to get out of date very quickly.

For example, let's say you're adding a new feature to your application, and it requires the variable FOO to be set. While you're developing locally, you likely have a .env file that looks something like:

APPLICATION_SECRET=supersekrit

# I got this FOO from the detailed process documented at: http:://wiki.example.com/how_to_get_a_foo
FOO="My super secret value for foo"

Working on large teams, it's common to share these .env files somewhere secure where all developers have access to them. Retrieval is often integrated into application startup and/or bootstrap processes.

But working on open source projects or teams with less trust and less shared infrastructure, it's more common to share an env.sample. ess automatically keeps the sample file in sync with .env, so you don't have to. Your .env file stays the same, and is automatically converted to the following env.sample:

APPLICATION_SECRET=<APPLICATION_SECRET>

# I got this FOO from the detailed process documented at: http:://wiki.example.com/how_to_get_a_foo
FOO=<FOO>

It's even possible to provide default/example values for every environment variables with the --example flag.

Command Flags

Name	Description	Example	Default
--env-file	The name of the environment file	--env-file=.secrets	--env-file=.env
--debug	Enable debugging	--debug	false
--skip-git-add	Skip performing git add after syncing	--skip-git-add	false
--sample-file	The name of the sample environment file	--sample-file=secrets.example	--sample-file=env.sample
--example	Provide examples for specific environment variables	--example=FOO="Example FOO" --example=BAR="Example BAR"	--example=VAR=<VAR>

Pre-commit Configuration Examples

Default configuration

repos:
-   repo: https://github.com/acaloiaro/ess.git
    rev: v2.6.0
    hooks:
      - id: ess

Customize .env and env.sample paths

repos:
-   repo: https://github.com/acaloiaro/ess.git
    rev: v2.6.0
    hooks:
      - id: ess
        args: ['--env-file=.env_file', '--sample-file=env_file.sample']

Customize variable example values

Sometimes environment variables need to conform to specific formats, and it's necessary to provide better documentation. For this reason, environment variable examples may be provided in lieu of the default behavior, which is to use the environment variable name surrounded by <brackets like this> in sample files.

repos:
-   repo: https://github.com/acaloiaro/ess.git
    rev: v2.6.0
    hooks:
      - id: ess
        args: [--example=FOO="Provide your foo here", --example=BAR="You can fetch bars from https://example.com/bars"]

Example environment file .env

FOO=the_value_of_my_secret_foo
BAR=the_value_of_my_secret_bar

Example sample file output env.sample

FOO=Provide your foo here
BAR=You can fetch bars from https://example.com/bars