JetBrains Space Help

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 excluding job.startOn, job.git, job.container.kotlinScript, and job.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 {{ ... \\}}.

job("Parameterized build") { // Users will be able to redefine these parameters in custom job run. // See the 'Customize job run' section parameters { text("build-image", value = "amazoncorretto:17-alpine3.15") text("build-command", value = "build --no-configuration-cache") } container("{{ build-image }}") { shellScript { content = "./gradlew {{ build-command }}" } } }

You can use parameters to get project secrets:

job("Deploy (project secrets)") { parameters { // plain text parameters text("terraform-image", "hashicorp/terraform:1.29") text("target-env", "dev") // Secrets are taken from project settings. // See the 'Use project secrets and parameters' section secret("aws-id", "{{ project:dev-aws-access-key-id }}") secret("aws-secret", "{{ project: dev-aws-secret-access-key }}") } container("{{ terraform-image }}") { // You can assign param values to env variables // See 'Pass parameters and secrets as environment variables' env["AWS_ACCESS_KEY_ID"] = "{{ aws-id }}" env["AWS_SECRET_ACCESS_KEY"] = "{{ aws-secret }}" shellScript { content = """ set -e cd deployments/{{ target-env }} terraform init terraform apply -auto-approve """ } } }

You can also support custom run scenarios where users can customize parameter values before the run.

job("Deploy (custom run)") { startOn {} // disable automatic git push trigger // During a custom run, a user can choose between 'dev' and 'prod' values parameters { text("env", value = "dev") { options("dev", "prod") } } host(displayName = "Setup parameters") { kotlinScript { api -> val env = api.parameters["env"] when (env) { "dev" -> { api.parameters["target-url"] = "my-app.dev.com" // You can use the 'Ref' class to reference a parameter in 'kotlinScript' api.secrets["deploy-token"] = Ref("project:dev-deploy-token") } "prod" -> { api.parameters["target-url"] = "my-app.com" api.secrets["deploy-token"] = Ref("project:prod-deploy-token") } } } } host(displayName = "Deploying to {{ target-url }}") { env["TOKEN"] = "{{ deploy-token }}" shellScript { content = """ # do deploy.. """ } } }

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 more

  • Project 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 the job.parameters block. Learn more

  • System 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 the run: 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 the worker: prefix. For example, "{{ worker:hostname }}".

    Learn more

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:

job("Use custom parameters") { parameters { // Simple text parameter with optional description text("text-param", value = "default-value", description = "This is a text param") // Text parameter with no default value. The job will fail // if a user doesn't specify its value before a custom run text("param-no-default") // Multiline text parameter text("param-multiline", value = "default-value", multiline = true) // Text parameter that doesn't allow changing its default value text("param-no-override", value = "non-overridable-value", allowCustomRunOverride = false) // Drop-down list of values text("param-options", value = "two") { options("one", "two", "three") } // List with multiple value choice text("param-options-multiple-choice", value = "two") { options("one", "two", "three") { allowMultiple = true // optionally, you can specify how the values must be separated valueSeparator = "," } } // Project secret secret("token", value = "{{ project:auth-token }}", description = "Auth token") } // here go job steps... }

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:

Custom run window

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.

job("Use job parameter") { parameters { text("my-param", value = "ABC123") secret("my-secret", value = "{{ project:password }}") } container(displayName = "Param value from env var", image = "ubuntu") { env["MY_PARAM"] = "{{ my-param }}" env["MY_SECRET"] = "{{ my-secret }}" // to get env vars in a shell script, escape the $ symbol in a // Kotlin way, e.g., ${'$'}JB_SPACE_API_URL shellScript { content = """ echo "Get my-param value from env var - ${'$'}MY_PARAM" if [ ${'$'}MY_SECRET != "1234" ]; then echo "Wrong password!" fi """ // Output: // Get my-param value from env var - ABC123 // Wrong password! } } }

To get an environment variable in the Kotlin script, use System.getenv():

job("Use job parameter") { parameters { text("my-param", value = "ABC123") } container(displayName = "Param value from env var kotlin", image = "ubuntu") { env["MY_PARAM"] = "{{ my-param }}" kotlinScript { api -> val myParam = System.getenv("MY_PARAM") println( """ Get my-param value from env var - $myParam """ ) // Output: // Get my-param value from env var - ABC123 } } }

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.

job("Reuse params") { // create a parameter container(displayName = "Set param", image = "amazoncorretto:17-alpine") { kotlinScript { api -> api.parameters["myName"] = "Anna" // to delete a parameter, use api.parameters().remove(key: String) } } // get parameter value in a shell script container(displayName = "Get param shell", image = "ubuntu") { shellScript { content = "Hi {{ myName }}!" } // Output: // Hi Anna! } // get parameter value in Kotlin code container(displayName = "Get param kotlin", image = "amazoncorretto:17-alpine") { kotlinScript { api -> println("Hi ${api.parameters["myName"]}!") } // Output: // Hi Anna! } }

For example, you can use this feature to run a step in an image built in the previous step:

job("Reuse created image") { // run step on a self-hosted or cloud worker host(displayName = "Generate an image tag") { // use kotlinScript blocks for advanced usage of parameters kotlinScript { api -> var imageTag if (api.gitBranch() == "refs/heads/main") { imageTag = "release" } else { imageTag = api.gitBranch() .replace("refs/heads/", "") .replace("/", "_") } imageTag = imageTag + "-" + api.gitRevision() api.parameters["imageTag"] = imageTag } } host(displayName = "Publish image") { // publish image to Space Packages registry dockerBuildPush { push = true tags { +"{{ imageTag }}" } } } // use the newly-built image to run a step container(image = "registry.mycompany.jetbrains.space/p/projectName/containerRepo/myImage:{{ imageTag }}") { // ... } }

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

  1. Open the desired project.

  2. On the project sidebar menu, choose Settings, then Secrets and Parameters.

  3. Click Create and choose Secret or Parameter.

  4. 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

  1. 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, and job.container.args blocks (same refers to all corresponding job.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 - ***** } } }

  2. 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.

    Show usages of secrets and params
Migrate from legacy secrets and parameters

Earlier, it was possible to use the Secrets and Params 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 the Secrets or Params functions, we strongly recommend that you replace them with the job.parameters.secret and job.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.

job("SSH auth") { parameters { // 'private-ssh-key' secret must be created in the project secret("private-key", "{{ project:private-ssh-key }}") } // this could be a 'container' step as well host { fileInput { source = FileSource.Text("{{ private-key }}") localPath = "/root/.ssh/id_rsa" } // here goes the rest of the script } }

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 in kotlinScript. Learn more about parameter scopes

  • Inside a kotlinScript block:

    • Use an API method that returns the required variable value, e.g., api.executionNumber(). The corresponding API methods always return String values.

    • Use the parameters API to get values by parameter names, e.g., api.parameters["run:number"].

For example:

job("Use configured parameter") { parameters { // assign a provided param to a configured param text("run-number-param", value = "{{ run:number }}") } container(displayName = "Print provided param value shell", image = "ubuntu") { shellScript { content = """ echo "Run number from env var - ${'$'}JB_SPACE_EXECUTION_NUMBER" echo "Run number from provided param - {{ run:number }}" echo "Run number from job param - {{ run-number-param }}" """ } // Output: // Run number from env var - 1 // Run number from provided param - 1 // Run number from job param - 1 } container(displayName = "Print provided param value kotlin", image = "ubuntu") { kotlinScript { api -> println("Run number from env var - " + System.getenv("JB_SPACE_EXECUTION_NUMBER")) println("Run number from API - " + api.executionNumber()) println("Run number from parameters API - " + api.parameters["run-number-param"]) } // Output: // Run number from env var - 1 // Run number from API - 1 // Run number from parameters API - 1 } }

General

Environment variable

Predefined name

API method

Description

JB_SPACE_API_URL

—

spaceUrl()

The URL of your JetBrains Space instance. For example: mycompany.jetbrains.space

Project settings

Environment variable

Predefined name

API method

Description

JB_SPACE_PROJECT_ID

{{run:project.id}}

projectId()

The ID of the current project.

JB_SPACE_PROJECT_KEY

{{run:project_key}}

projectKey()

The key of the current project.

—

{{run:file-caches.default-repository}}

—

The name of the default cache repository.

Job settings

Environment variable

Predefined name

API method

Description

JB_SPACE_CLIENT_TOKEN

—

spaceClientToken()

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.

JB_SPACE_CLIENT_ID, JB_SPACE_CLIENT_SECRET

—

spaceClientId(), spaceClientSecret()

As an alternative to an access token, the script can authorize with temporary OAuth 2.0 credentials.

JB_SPACE_GIT_REVISION

{{run:git-checkout.commit}}

gitRevision()

The current Git commit ID.

JB_SPACE_GIT_BRANCH

{{run:git-checkout.ref}}

gitBranch()

The current Git branch.

JB_SPACE_GIT_REPOSITORY_NAME

{{run:git-checkout.repositories}}

gitRepositoryName()

A comma-separated list of the checked-out repositories:

—

{{run:trigger.type}}

—

The type of trigger used to initiate job run. Possible values: manual, git-push, schedule, git-branch-deleted, code-review-opened, code-review-closed.

—

{{run:trigger.manual.user.id}}

—

The ID of the user who triggered job run. Relevant only if the job was run manually by a Space user.

—

{{run:trigger.manual.application.id}}

—

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.

—

{{run:trigger.manual.git-checkout.ref}}

—

The current Git branch. Relevant only if a user have chosen a particular commit during custom run.

—

{{run:trigger.manual.git-checkout.commit}}

—

The current Git commit ID. Relevant only if a user have chosen a particular commit during custom run.

—

{{run:trigger.git-push.commit}}

—

The ID of the commit that triggered job run. Relevant only if the gitPush trigger is enabled.

—

{{run:trigger.git-push.ref}}

—

The branch which triggered job run. Relevant only if the gitPush trigger is enabled.

—

{{run:trigger.git-push.repository}}

—

The repository which triggered job run. Relevant only if the gitPush trigger is enabled.

—

{{run:trigger.git-branch-deleted.refs}}

—

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., refs/heads/branch1,refs/tags/v1-dev.

—

{{run:trigger.code-review-opened.review.id}}, {{run:trigger.code-review-closed.review.id}}

—

The ID of the review that triggered job run. Relevant only if the codeReviewOpened or codeReviewClosed trigger is enabled.

—

{{run:trigger.code-review-opened.source.ref}}, {{run:trigger.code-review-closed.source.ref}}

—

The branch that goes through the code review. Relevant only if the codeReviewOpened or codeReviewClosed trigger is enabled.

—

{{run:run:trigger.code-review-opened.source.commit}}, {{run:run:trigger.code-review-closed.source.commit}}

—

The ID of the commit that goes through the code review. Relevant only if the codeReviewOpened or codeReviewClosed trigger is enabled.

—

{{run:trigger.code-review-opened.target.ref}}, {{run:trigger.code-review-closed.target.ref}}

—

The branch where the changes are supposed to be merged after the code review. Relevant only if the codeReviewOpened or codeReviewClosed trigger is enabled.

—

{{run:run:trigger.code-review-opened.target.commit}}, {{run:run:trigger.code-review-closed.target.commit}}

—

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.

JB_SPACE_EXECUTION_ID

{{run:id}}

executionId()

A unique ID of the current run (build). You can use it to refer to a particular build using the Space API.

—

{{run:job.id}}

—

A unique ID of the current job.

—

{{run:job.repository}}

—

The name of the Git repository where the current .space.kts is defined.

JB_SPACE_EXECUTION_NUMBER

{{run:number}}

executionNumber()

The current job run number (build number). For example, you can use it to generate application version number. Learn more

JB_SPACE_EXECUTION_URL

{{run:url}}

executionUrl()

A link to the current job execution.

Step (worker) settings

Environment variable

Predefined name

API method

Description

SPACE_WORKER_SERVERURL

—

—

The URL of the JetBrains Space instance assigned to the worker. For example, mycompany.jetbrains.space

SPACE_WORKER_TOKEN

—

—

An authorization token issued to the worker. The worker uses it to authenticate in Space.

SPACE_WORKER_DATADIR

—

—

The path to the directory where the script downloads all required data: project sources, file share, and Automation-specific data.

SPACE_WORKER_HOSTNAME

—

—

A host name of the worker.

SPACE_WORKER_CPU, SPACE_WORKER_MEM

{{worker:cpu}}, {{worker:memory}}

—

The system resources available on the host machine that runs the worker agent: CPU cores in mCPU, and RAM in MB.

—

{{worker:hostname}}

—

The hostname of the worker machine.

—

{{worker:os.arch}}, {{worker:os.name}}, {{worker:os.version}}

—

Target CPU architecture of the operating system (OS), OS type, and OS version on the worker.

View job and step parameters

  1. Navigate to the project.

  2. On the sidebar menu, choose Jobs.

  3. Select a job.

  4. 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.

Last modified: 28 February 2023
Space Cloud Workers Build Artifacts and Cache