Secrets and Parameters

Secrets and parameters are project-wide variables that you can use in your Automation scripts:

Parameters – variables that are frequently used throughout your Automation scripts. For example, a URL of an external service.
Secrets – variables stored in the AES-encrypted format. For example, credentials to an external service.
Once you delete a secret from a project, it is instantly deleted from the storage (if there are running jobs that use the secret, it will be deleted once the jobs finish running).
To use secrets and parameters in jobs, you must first create them in the project settings.
Vault parameters – secrets stored in external HashiCorp Vault storage. Before you can use Vault parameters, you must configure a connection to the storage.

Note that Automation hides values of secrets and Vault parameters in job logs for security reasons.

Creating secrets and parameters

Open the desired project.
On the project sidebar menu, choose Settings, then Secrets and Parameters.
Click Create and choose Secret or Parameter.
Specify
- Key: a variable name. You will use this name to reference this variable in your scripts.
- Value: a variable value.
Note the limitations:
- Secrets and parameters exist only in a scope of a particular project. So, if you create a secret or a parameter in one project, you cannot use them in other projects.
- Keys of secrets and parameters must be unique within a project. A secret and a parameter with the same key are also not allowed.
- A key must be no longer than 128 characters and can only contain alphanumeric characters ([a-z], [A-Z], [0-9]), dashes (-), or underscores (_).
- Keys are case-insensitive.
- Max secret's or parameter's value size is 30KB. Note that the max total size of all container arguments, environment variables, secrets, and parameters is also limited by 30KB. For example, if you provide a secret of 30KB and an argument of 1KB to a step, the step will fail.

Creating Vault parameters

In addition to its secret storage, Space also supports external HashiCorp Vault storage. Once you configure a connection to a Vault server, you can use variables from the storage the same way you use project parameters.

Prerequisites: You have a working Vault server with a configured AppRole. The server stores secrets required by the build script.

To configure connection to a Vault server

Open the desired project.
On the project sidebar menu, choose Settings, then Vault Connections.
Click New connection and specify a connection Name and other settings:
- Vault URL: a URL of the Vault server in the https://vaultserver:port format.
- AppRole ID and AppRole Secret ID: credentials used by Space to log in to the Vault server.
- Parameters namespace: (optional) an additional connection identifier. If a project has multiple Vault connections, Parameters namespace lets you specify which connection must be used to resolve a particular parameter.
- Vault namespace: (optional) a Vault namespace that is used in multi-tenant Vault configurations.
Click Test connection and if connection is successfull, click Create.

To create a Vault parameter

Open the desired project.
On the project sidebar menu, choose Settings, then Secrets and Parameters.
Click Create and choose Vault parameter.
Specify
- Key: a variable name. You will use this name to reference this variable in your scripts.
- Path: a Vault secret path in the Key/Value v1 or v2 secrets engine format. For example, /aws/sts/mysecret.
- Field: (optional) a field name. If a secret has multiple fields, specify the field which value you want to get in an Automation job. If a secret has multiple fields, but you don't specify a field name, Automation will try to get a field named value.
- Namespace: (optional) an identifier of the Vault connection that must resolve the parameter. The Namespace must match the parameters namespace specified for the Vault connection.
Click Save.

Alternatively, you can create a Vault parameter as an ordinary parameter. In this case, in the parameter's Value, specify a full path to the secret in Vault in the vault:namespace:/secret_path/field_name format. For example:

vault:/secret/password: get a value of the secret that has only one field named password.
vault:/secret/credentials!/password: get a value of the password field of the /secret/credentials! secret.
vault:/secret/json!/store.books[0].category: get a value corresponding to the JsonPath search query (dot notation) in the /secret/json secret stored as a JSON object.
vault:/secret/json!/['store'].['books'][0].['category']: get a value corresponding to the JsonPath search query (bracket notation) in the /secret/json secret stored as a JSON object.
vault:test:/secret/credentials!/password: get a value of the password field of the /secret/credentials secret using the Vault connection with the test parameters namespace.

Using secrets and parameters

Use the Secrets and Params functions to assign the value of a secret or a parameter to an environment variable.
Use the environment variable inside shellScript or kotlinScript.

For example:

            job("Secrets and params") {
                // get param, secret, and vault param in a shell script
                container(displayName = "Show pwd", image = "ubuntu") {
                    env["URL"] = Params("bintray-repo-url")
                    env["PSWRD"] = Secrets("bintray-repo-password")
                    env["TOKEN"] = Params("token-from-vault")

                    shellScript {
                        content = """
                            echo My password for ${'$'}URL
                            echo is  ${'$'}PSWRD
                            echo Token from Vault is ${'$'}TOKEN
                        """
                    }
                }

                // get param, secret, and vault param in Kotlin code
                container(displayName = "Show pwd", image = "ubuntu") {
                    env["URL"] = Params("bintray-repo-url")
                    env["PSWRD"] = Secrets("bintray-repo-password")
                    env["TOKEN"] = Params("token-from-vault")

                    kotlinScript {
                        val url = System.getenv("URL")
                        val pswrd = System.getenv("PSWRD")
                        val token = System.getenv("TOKEN")
                        println("""
                            My password for $url
                            is $pswrd
                            Token from Vault is $token
                        """)
                    }
                }
            }
        

Last modified: 07 November 2022