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.
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 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.
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.
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.
Then you connect the
default-concurrency-settings block to the app
foo-foo. Now you set your local branch to
$ 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
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:
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
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
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.
Environment variables are resolved in the following order of precedence, with later items in the list overriding earlier items:
- Block base environments (precedence determined by order of connected blocks--later blocks override earlier blocks)
- Block branches (precedence determined by order of connected blocks--later blocks override earlier blocks)
- Block local overrides (precedence determined by order of connected blocks--later blocks override earlier blocks)
- App base environment
- App branch
- App local overrides
- Existing local environment variables (unless
-fflag is set when calling
Updated over 1 year ago