Branches

Branches allow you to create derivative environments that inherit from base environments like development, staging, or production. You can add additional variables or override existing variables from the base environment. If it's a development branch, it can then be checked out locally using envkey checkout branch-name. For a server, an ENVKEY can be generated that connects to the branch.

📘

Upgrading from v1?

Branches in EnvKey v2 are the same as sub-environments in EnvKey v1.

Using a Branch in Development

When a new feature is in-progress, it may require new environment variables, or changes to variables that are already set. That's a perfect use case for branches. Once the branch has been created, it can be checked out by any user with access to the app like this:

$ cd ~/projects/some-app
$ envkey checkout feature-1

You can return to the main development branch like this:

$ envkey checkout development

Or if you want to type just a little bit less:

$ envkey checkout dev

Local Overrides

Local overrides allow you to set user-specific overrides. They can be set for human users or CLI keys. You can add additional variables or override existing variables.

Say, for example, that each user with access to an EnvKey app requires a different value for a AWS_SECRET_KEY variable in their development environment. That's a perfect reason to use local overrides. Set the appropriate value for each user. Now when they load the development environment with envkey-source, the AWS_SECRET_KEY environment value will contain the value you set for them.

Blocks, Branches, and Local Overrides

Branches can be created and local overrides set for both EnvKey apps and EnvKey blocks.

Let's say you create branch called feature-1 off of the Development environment in an app called foo-foo. You add a variable to this branch.

SOCKET_URL=127.0.0.1:9999

Now you create a block called default-concurrency-settings, and then a branch off the block's Development environment called feature-1. Then you add a variable to the block's branch.

NUM_THREADS=4

Then you connect the default-concurrency-settings block to the app foo-foo. Now you set your local branch to feature-1.

$ cd ~/projects/foo-foo
$ envkey checkout feature-1

Your development environment will now contain both variables:

$ envkey-source -e 'echo $SOCKET_URL; echo $NUM_THREADS;'
> 127.0.0.1:9999
> 4

Local overrides stack in a similar way. Let's say you set a local override for yourself in the app foo-foo.

AWS_SECRET=secret-key

And then you also set a local override for yourself in the default-concurrency-settings block, since you have a particularly beefy machine that can handle more concurrency than your servers:

NUM_THREADS=16

Your development environment will now contain:

$ envkey-source -e 'echo $SOCKET_URL; echo $AWS_SECRET; echo $NUM_THREADS;'
> 127.0.0.1:9999
> secret-key
> 16

Local Environment Variables

When you integrate with envkey-source EnvKey will not overwrite existing environment variables or additional variables set in the .env file your ENVKEY is loaded from. While it's usually better to use branches or local overrides, this gives you one more option for customizing environments that otherwise share the same configuration.

Say you have DATABASE_NAME set in EnvKey, but you want to temporarily connect to a different database. If you simply set your own DATABASE_NAME environment variable, EnvKey will defer to it.

The same thing can be accomplished by adding additional lines to your .env file. For example:

# ~/.env file

ENVKEY=...
DATABASE_NAME=other-db-name

Now other-db-name will override the EnvKey value.

$ envkey-source -f -- echo '$DATABASE_NAME'
> other-db-name

You can reverse this behavior and force envkey-source to override any existing variables by using the -f flag when integrating:

$ envkey-source -f -- echo '$DATABASE_NAME'
> original-db-name

🚧

Watch out for local environment variables

While the behavior described above can be useful for overriding EnvKey values, it can also be confusing in some circumstances. If you have an environment variable set locally CACHE_HOST=0.0.0.0, then add the same var to EnvKey with a different value: CACHE_HOST=cache.company-services.com, and then you forget that you had the local environment variable set, EnvKey will defer to the locally set variable and it might seem to you that EnvKey is giving you the wrong value, or isn't updating.

So if it seems like EnvKey is giving you the wrong values, make sure you haven't inadvertently set any local environment variables that are overriding your EnvKey vars.

Resolution Order and Precedence

Environment variables are resolved in the following order of precedence, with later items in the list overriding earlier items:

1. Block base environments (precedence determined by order of connected blocks--later blocks override earlier blocks)
2. Block branches (precedence determined by order of connected blocks--later blocks override earlier blocks)
3. Block local overrides (precedence determined by order of connected blocks--later blocks override earlier blocks)
4. App base environment
5. App branch
6. App local overrides
7. Existing local environment variables (unless -f flag is set when calling envkey-source)