Parameters and Secrets
Parameters provide an Automation script with data required for its execution. Parameters let you:
Customize a job run – With the help of parameters, other Space users can provide their custom values to a script, e.g., choose another Docker image for a step, provide custom command-line arguments, etc.
Pass string values between steps – For example, pass the result of a step run to the next step.
Provide project secrets and parameters to a job – Such parameters are common for the entire project, e.g., this may be a URL of some service, a file path, etc. Secrets let you provide jobs with sensitive data, e.g., passwords or access tokens.
Get details about job execution context – With the help of provided parameters, you can get a current Git commit ID, a job execution number, information about the worker operating system, and other context data.
Parameterize your Automation job
To define parameters and secrets in a job, use the
job.parameters.text
job.parameters.secret
blocks.To get a parameter in a job, specify its name in a string inside double curly braces:
"{{ my-param }}"
. You can do this in any string inside any DSL block excludingjob.startOn
,job.git
,job.container.kotlinScript
, andjob.host.kotlinScript
.To get parameters inside the
kotlinScript
blocks, use one of the options:If your script contains strings with curly braces that are not used for parameters, you should escape them:
\\{{ ... }}
and/or{{ ... \\}}
.
You can use parameters to get project secrets:
You can also support custom run scenarios where users can customize parameter values before the run.
Parameter scopes
Job scope – user-defined parameters relevant only for a particular Automation job. You must define job parameters in the
job.parameters
block or create them dynamically during the job run. To reference a job parameter, specify its name:"{{ param-name }}"
. Learn moreProject scope – user-defined parameters and secrets relevant for the whole project. You must define project parameters in the project settings. To reference a project parameter, specify its name preceded with the
project:
prefix. For example,"{{ project:access-token }}"
. It is possible to reference a project parameter only in thejob.parameters
block. Learn moreSystem scope (provided parameters) – Space-defined parameters that provide information about job execution context:
run
– sub-scope that provides data on current job run, e.g., a Git commit ID, a job execution number, a project ID, and so on. To reference a run parameter, specify its name preceded with therun:
prefix. For example,"{{ run:number }}"
.worker
– sub-scope that provides data on run environment, e.g., a worker hostname, info about operating system, and so on. To reference a worker parameter, specify its name preceded with theworker:
prefix. For example,"{{ worker:hostname }}"
.
Customize job run
Job parameters allow users to change the default parameter value before running the script. To run a job with customized parameters, users must use the custom run option.
The job.parameters.text
function lets you define various types of customizable parameters. All possible options are shown in the following example:
In order the parameters specified in the script appeared in the custom run window, the script must be processed by Automation (the processing runs automatically after a user pushes changes to the .space.kts
file). The custom run window for the script above will look like follows:

Pass parameters and secrets as environment variables
To assign a parameter or a secret to an environment variable, use the job.container.env
or job.host.env
functions.
To get an environment variable in the Kotlin script, use System.getenv()
:
Pass parameters and secrets between steps
Sometimes it is necessary to pass execution context (e.g., script run results) from one Automation step to another. To create a parameter or a secret from within a step, you should use the parameters
API. The API is available only inside the kotlinScript
block: the container that runs the step must include JRE/JDK 11 or later.
For example, you can use this feature to run a step in an image built in the previous step:
Use project secrets and parameters
Project parameters are available inside any Automation job within a project. There are two types of project parameters:
Plain text parameters – typically, these are parameters frequently used throughout your Automation scripts. For example, a URL of an external service.
Secrets – parameters stored in the AES-encrypted format. For example, a password or an access token to an external service. Automation hides secret values in job logs for security purposes.
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 define project 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 parameter name. You will use this name to reference this parameter in your scripts.
Value: a parameter value.
Limitations:
Secrets and parameters exist only in the 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 (_
).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.
To use project secrets and parameters
Follow the rules:
To get a project parameter or secret, use its key preceded with the
project:
prefix:"{{ project:param-key }}"
.You can get secrets only inside the
job.parameters
,job.container.env
,job.container.shellScript.args
, andjob.container.args
blocks (same refers to all correspondingjob.host
blocks).
For example:
job("Use project params") { // E.g., a parameter and a secret // 'bintray-repo-url' and 'bintray-repo-password' // exist in the project settings parameters { // you can assign project secrets and params to configured params text("url", value = "{{ project:bintray-repo-url }}") secret("password", value = "{{ project:bintray-repo-password }}") } // Get project parameter values in a shell script container(displayName = "Print param value shell", image = "ubuntu") { env["URL"] = "{{ project:bintray-repo-url }}" // The only way to get a secret in a shell script is an env variable env["PSWRD"] = "{{ project:bintray-repo-password }}" shellScript { content = """ echo "Url from conf param - {{ url }}" echo "Url from env var - ${'$'}URL" echo "Password from env var - ${'$'}PSWRD" echo "Url from project param directly - {{ project:bintray-repo-url }}" # It's not possible to directly reference secrets from a shell script. # The next commented lines would fail. # echo "Password from conf param - {{ password }}" # echo "Password from project param - {{ project:bintray-repo-password }}" """ // Output: // Url from conf param - http://example.com // Url from env var - http://example.com // Password from env var - ***** // Url from project param directly - http://example.com } } // Get project parameter values in a Kotlin script container(displayName = "Print param value kotlin", image = "amazoncorretto:17-alpine") { env["URL"] = "{{ project:bintray-repo-url }}" env["PSWRD"] = "{{ project:bintray-repo-password }}" kotlinScript { api -> println("Url from env var - " + System.getenv("URL")) println("Url from API - " + api.parameters["url"]) println("Password from env var" + System.getenv("PSWRD")) // An advanced use case is the Ref class that holds a // reference to a secret or a parameter: // Ref("project:my-param").toString() == "{{ project:my-param }} // See the example below api.secrets["service-password"] = Ref("project:bintray-repo-password") println("Password from Ref" + api.secrets["service-password"]) // Output: // Url from env var - http://example.com // Url from env API - http://example.com // Password from env var - ***** // Password from Ref - ***** } } }To see in which jobs a particular secret or parameter is used, open Secrets and Parameters in project settings and click Show usages next to the desired secret or parameter.
- Migrate from legacy secrets and parameters
Earlier, it was possible to use the
Secrets
andParams
functions for getting values of project secrets and parameters. These functions are deprecated and will be removed in the future. Therefore, if your Automation scripts use theSecrets
orParams
functions, we strongly recommend that you replace them with thejob.parameters.secret
andjob.parameters.text
blocks.Legacy script
job("Legacy way to use secrets and params") { container(displayName = "Show pwd", image = "ubuntu") { env["URL"] = Params("bintray-repo-url") env["PSWRD"] = Secrets("bintray-repo-password") shellScript { content = """ echo My password for ${'$'}URL echo is ${'$'}PSWRD """ } } }Replace with
job("New way to use secrets and params") { parameters { text("url", "{{ project:bintray-repo-url }}") secret("password", "{{ project:bintray-repo-password }}") } container(displayName = "Show pwd", image = "ubuntu") { env["URL"] = "{{ url }}" env["PSWRD"] = "{{ password }}" shellScript { content = """ echo My password for ${'$'}URL echo is ${'$'}PSWRD """ } } }
Provide project secrets as files
Some build steps may require sensitive data in the form of a file. For example, if your Automation script authenticates on a remote server using SSH, it must have access to the private key file. Of course, it's not safe to store the private key file in the project sources. Instead, you can store the string with the key as a project secret and get it in the script as a file. To do this, use the fileInput
block.
Use provided parameters
Automation provides a number of predefined parameters which you can use in your build scripts, e.g., a job run number, a Git branch name and commit ID, a URL of your Space instance, and so on.
There are several ways to get the value of a provided parameter (some of these ways may not be available for certain variables):
Use a predefined environment variable, e.g.
$JB_SPACE_EXECUTION_NUMBER
.Use a predefined parameter name, e.g.,
"{{ run:number }}"
. Doesn't work inkotlinScript
. Learn more about parameter scopesInside a
kotlinScript
block:Use an API method that returns the required variable value, e.g.,
api.executionNumber()
. The corresponding API methods always returnString
values.Use the
parameters
API to get values by parameter names, e.g.,api.parameters["run:number"]
.
For example:
General
Environment variable | Predefined name | API method | Description |
---|---|---|---|
| — |
| The URL of your JetBrains Space instance. For example: |
Project settings
Environment variable | Predefined name | API method | Description |
---|---|---|---|
|
|
| The ID of the current project. |
|
|
| The key of the current project. |
— |
| — | The name of the default cache repository. |
Job settings
Environment variable | Predefined name | API method | Description |
---|---|---|---|
| — |
| Temporary OAuth 2.0 access token issued to the current script. The script can use it to authorize in various Space modules. For example, you can use it to authorize the script in a Packages repository in order to publish build artifacts. |
| — |
| As an alternative to an access token, the script can authorize with temporary OAuth 2.0 credentials. |
|
|
| The current Git commit ID. |
|
|
| The current Git branch. |
|
|
| A comma-separated list of the checked-out repositories:
|
— |
| — | The type of trigger used to initiate job run. Possible values: |
— |
| — | The ID of the user who triggered job run. Relevant only if the job was run manually by a Space user. |
— |
| — | The ID of the application that triggered job run. Relevant only if the job was run by an HTTP API call from a registered application. |
— |
| — | The current Git branch. Relevant only if a user have chosen a particular commit during custom run. |
— |
| — | The current Git commit ID. Relevant only if a user have chosen a particular commit during custom run. |
— |
| — | The ID of the commit that triggered job run. Relevant only if the gitPush trigger is enabled. |
— |
| — | The branch which triggered job run. Relevant only if the gitPush trigger is enabled. |
— |
| — | The repository which triggered job run. Relevant only if the gitPush trigger is enabled. |
— |
| — | The list of branches/tags that were deleted. Relevant only if the gitBranchDeleted trigger is enabled. A comma is used as a separator, e.g., |
— |
| — | The ID of the review that triggered job run. Relevant only if the codeReviewOpened or codeReviewClosed trigger is enabled. |
— |
| — | The branch that goes through the code review. Relevant only if the codeReviewOpened or codeReviewClosed trigger is enabled. |
— |
| — | The ID of the commit that goes through the code review. Relevant only if the codeReviewOpened or codeReviewClosed trigger is enabled. |
— |
| — | The branch where the changes are supposed to be merged after the code review. Relevant only if the codeReviewOpened or codeReviewClosed trigger is enabled. |
— |
| — | The ID of the commit that is supposed to be merged after the code review. Relevant only if the codeReviewOpened or codeReviewClosed trigger is enabled. |
|
|
| A unique ID of the current run (build). You can use it to refer to a particular build using the Space API. |
— |
| — | A unique ID of the current job. |
— |
| — | The name of the Git repository where the current |
|
|
| The current job run number (build number). For example, you can use it to generate application version number. Learn more |
|
|
| A link to the current job execution. |
Step (worker) settings
Environment variable | Predefined name | API method | Description |
---|---|---|---|
| — | — | The URL of the JetBrains Space instance assigned to the worker. For example, mycompany.jetbrains.space |
| — | — | An authorization token issued to the worker. The worker uses it to authenticate in Space. |
| — | — | The path to the directory where the script downloads all required data: project sources, file share, and Automation-specific data. |
| — | — | A host name of the worker. |
|
| — | The system resources available on the host machine that runs the worker agent: CPU cores in mCPU, and RAM in MB. |
— |
| — | The hostname of the worker machine. |
— |
| — | Target CPU architecture of the operating system (OS), OS type, and OS version on the worker. |
View job and step parameters
Navigate to the project.
On the sidebar menu, choose Jobs.
Select a job.
To view all parameters in a job, open the Parameters tab.
To view parameters in a particular step, open the Steps tab, choose a particular step, and open its Parameters tab.