Modern applications and continuous integration workflows often need to store values that are sensitive and should not be stored in version control or in any plain text format. For example, the credentials to access an API should never be stored in version control, especially in a public repository.

The State Tool has a secret management solution built in for managing these confidential values. You should store any database passwords, API keys, and other sensitive credentials your project needs access to as secrets.

A secret is similar to a constant, except that its value is securely stored on the ActiveState Platform. It is encrypted using RSA encryption in a manner that no one but you will ever be able to decrypt if you keep your password secure. Not even ActiveState knows the true value of your secrets. We only store the encrypted value.

The ActiveState Platform supports sharing secrets with the other users in your project. If the same database credentials are used by all members of a project, you can maintain a single secret value and share it securely with the team.

Secret Definitions versus Secret Values

It’s important to differentiate between a secret definition and a secret value. You can define a secret without it having a value assigned yet. When a secret is defined but it has no value then the user will be prompted for a value when the secret is being used.

Secret Scopes

When talking about secrets we need to also talk about secret scopes. A scope describes who the secret value “belongs to”. Currently we support two scopes, “user” and “project”.

The “user” scope denotes a secret value as belonging to a user. This means that when you define a secret that is “user scoped” that every user will have to set their own value for this secret, to which only they have access.

The “project” scope denotes a secret value as belonging to everyone in the project. This means that when someone defines a secret value for such a secret that everyone with permissions for the project will get access to this value.

Using secrets

Secrets are set and retrieved using State Tool commands on the command line, but you can use them in your activestate.yaml configuration file. You can reference secrets using $secrets This syntax for accessing a user-scoped secret named LOCATAION is the following:

 - name: HELLO
   value: Hello $secrets.user.LOCATION

The $secrets. prefix indicates that we want to “expand” our identifier as a secret, and the user.LOCATION bits identify it as a secret named LOCATION stored under the user. This syntax is compatible with the output of the “Usage” column when running state secrets to list your secrets. You can copy and paste that value right after the $secrets. prefix in your activestate.yaml file.

It’s important to note that you do not need to first define the user.LOCATION secret. If a secret does not yet exist you will instead be prompted for its value when you try to access it.