Manage Environment Variables and Secrets

Learn how to manage Environment Variables and Secrets across Apps and Environments.


A central element of Internal Developer Platforms is the ability to create new Environments whenever needed. This requires a solid approach to manage environment-specific configurations. Humanitec provides you with the required functionality to handle both, environment variables and secrets in a scalable and secure way.

Types of Variables

When looking at variables for externalized App configuration, you can distinguish between 3 different types of variables.



Static Environment Variables

Static Environment Variables are - as the name implies - static across all or most of the Environments of a specific App.

A good example is a variable to control the debugging or logging behavior of the Workloads in your App. You typically use a detailed level of logging in your development Environments that allows for better debugging while restricting logging to errors in your production Environment.

Dynamic Environment Variables

Dynamic Environment Variables have Environment-specific values.

Good examples are variables needed to connect to a database (such as username, hostname, and port). While each of the Environments of a specific App might use the same server, the databases themselves are Environment-specific.

You typically need some kind of placeholder system to enable Dynamic Environment Variables.


Secrets are very similar to Environment Variables with the main difference that you cannot retrieve them back in an unencrypted way once you entered them. They are resolved at deployment time to provide the required App configuration.

Good examples are passwords that you need to access databases.

Variable Hierarchy

Humanitec allows you to define Environment Variables and Secrets in a hierarchical way.

App Default Values

The highest hierarchical level is the App level. You can go to the App Settings Screen in each of your Apps and define Environment Variables that are important within the context of your App.

Example for Environment Variables in the App Settings

As you can see from the example above, you can define Environment Variables as well as Secrets on this level. The variables defined on App-level can be referenced within each Environment of the App by using ${values.KEY} on the Environment level.

Humanitec also allows you to provide a description for each variable you are defining. You can use the description to explain the variable or even to mention the team/person responsible for managing this variable which can become very handy especially in large organizations.

Environment Level

You currently cannot manage variables on the Environment level. We will add this functionality soon.

Workload Level

The lowest hierarchical level is the Workload level. You can edit Environment Variables and Secrets on the Workload Level from each Workload Details Screen.

Example for Environment Variables on the Workload Detail Page

As you can see in the example above you can reference the variables defined on the App level by using ${values.KEY} and Humanitec provides autocomplete suggestions. You can also define new variables just used for this workload.

Variable Substitutions

Variable Substitutions allow you to dynamically reference values that depend on the environment (e.g., the Workload's database name, auto-generated external DNS names, secrets). A variable substitution consists of a string that you enter in the value of an Environment Variable in a Workload’s configuration map. When you deploy your App, Humanitec will replace these strings with the values that they reference.

Database References

Variable substitution name



The name of the database that your module connects to.

externals. postgres.engine

The database engine used. Will always be POSTGRES.


The DNS name or IP of the database server.

externals. postgres.username

The username of the Postgres ROLE that has access to the database defined in name.

externals. postgres.password

The password of the Postgres ROLE that has access to the database defined in name.

externals. postgres.port

The port on the server defined by host.

Workload References

Variable substitution name



The in-cluster DNS name of the Workload.


The DNS name of the Workload, which is generated if you expose the Workload externally.