DSL Reference

The Automation DSL is a domain specific language whose goal is to help you write Space automation scripts. The DSL is based on Kotlin programming language. This means that you can use Kotlin data types and language constructs inside your scripts.

job

job is a defined task consisting of steps.

job(name: String, init: Task.() -> Unit)

	`name: String` is the name of the job
	`init` is the job content

For example:

                job("Hello World!") {
                    container(image = "hello-world")
                }
            

job.container

container runs a container and executes the specified command or script inside this container.

container(image: String, init: Container.() -> Unit = {})

container(displayName: String?, image: String, init: Container.() -> Unit = {})

displayName: String? is the step name displayed in the job run resutls on the Jobs page. If not specified, the image name will be shown.

image: String is the name of an image on

Docker Hub. An image name is enough, for example: container(image = "alpine:latest")
Space Packages. A full image URL is required, for example: container(image = "mycompany.registry.jetbrains.space/p/mpj/mydocker/myimage")

init function configures the container and runs specified commands and scripts. You can use the following methods and properties inside init:

	`mountDir: String` sets the absolute path to the directory where the Automation volume must be mounted. By default, `/mnt/space`. Learn more
	`workDir: String` a path to the working directory. All commands will be run from this directory. By default, the working directory is the directory with the project sources: `$mountDir/work/{git-repo-name}`. You can use `workDir` to set: An absolute path to the working directory. For example: `workDir = "/home/john-doe/myproject"` A relative path to the current working. For example: `workDir = "myproject"` will be resolved to `$moundDir/work/{git-repo-name}/myproject`. Learn more
	`user: String` specifies the user account that will be used to run commands and scripts inside the container.
	`args` provides arguments for a default image command or for `entrypoint`
	`entrypoint` overrides a default image command with the specified one
	`shellScript` runs the specified shell script
	`kotlinScript` runs Kotlin code
	`service` runs a container with a network-accessible service, for example, a database server
	`env` sets an environment variable in the container
	`resources` limits container resources (CPU and memory)

For example:

                job("Example") {
                    // in the container with 'gradle' image
                    container(image = "gradle") {
                        // run 'gradle build'
                        shellScript {
                            content = "gradle build"
                        }
                    }
                }
            

job.container.args

If entrypoint is specified, args provides arguments for the entrypoint command. Otherwise, args provides arguments for the default image command (for example, set by ENTRYPOINT). Each argument must be a separate string in the args array. If you specify more than one args, only the last one will take effect.

args(vararg args: String)

For example:

                job("Example args") {
                    container(image = "alpine") {
                        args("echo", "Hello World!")
                    }
                }
            

job.container.entrypoint

entrypoint runs the specified command overriding the default image command. This is equivalent to Docker's ENTRYPOINT. Command arguments must be provided as separate strings in the args array . If you specify more than one entrypoint, only the last one will take effect.

entrypoint(entryPoint: String)

For example:

                job("Example entrypoint") {
                    // override the default command set in 'myImage'
                    container(image = "myImage") {
                        entrypoint("/bin/sh")
                        args("echo", "Hello World!")
                    }
                }
            

job.container.shellScript

shellScript runs the provided shell script.

shellScript(init: ContainerShellScript.() -> Unit)

init function specifies the script and script interpreter. You can use the following properties inside init:

	`interpreter: String` specifies the interpreter used to run the script. By default, `/bin/sh`.
	`content: String?` specifies the shell script content. This can be a multiline string.
	`location: String?` specifies a path to the shell script file. This may be an absolute path or a path relative to the working directory.
	`args(vararg args: String)`, `args(args: Collection<String>)` provides arguments for the script file specified in `location`.

For example:

                job("Example shell scripts") {
                    container(image = "ubuntu") {
                        shellScript {
                            interpreter = "/bin/bash"
                            content = """
                                echo Username: $1' >> /mnt/space/share/myscript.sh
                                echo Password: $2' >> /mnt/space/share/myscript.sh
                                chmod +x /mnt/space/share/myscript.sh
                            """
                        }
                    }

                    container(image = "ubuntu") {
                        shellScript {
                            location = "/mnt/space/share/myscript.sh"
                            args("anna", "1234")
                        }
                    }
                    // In job logs, we'll see 'Username: anna Password: 1234'
                }
            

Note that marking the script file as executable with chmod +x is not necessary: Automation automatically sets the 'executable' flag for the script file specified in location.

job.container.kotlinScript

kotlinScript runs arbitrary Kotlin code. If you specify more than one kotlinScript, only the last one will be run. Note that in order to run a Kotlin script, the container image you use must include JRE/JDK 9 or later.

kotlinScript(init: ProcessKotlinScript.(ScriptAPI) -> Unit)

For example:

                job("Example kotlin script") {
                    container(image = "openjdk:11") {
                        kotlinScript { api ->
                            if (api.gitBranch() == "refs/heads/main") {
                                println("Running in main branch")
                            } else {
                                println("Running in custom branch")
                            }
                        }
                    }
                }
            

                job("Example script") {
                    container(image = "openjdk:11") {
                        kotlinScript { api ->
                            val totalMembers = api.space().teamDirectory.stats.getAllStats().totalMembers
                            val recipient = MessageRecipient.Member(ProfileIdentifier.Username("Anna"))
                            val content = ChatMessage.Text("Hi! Employees total is $totalMembers")
                            api.space().chats.messages.sendMessage(recipient, content)
                        }
                    }
                }
            

kotlinScript provides access to various APIs. The APIs let you work with particular Space modules or with build tools like Gradle. Currently, the following APIs are available:

Function	Returns	Description
`gradlew(vararg args: string)`	`Int`	Runs Gradle commands using the Gradle wrapper from the project sources. For example: `api.gradlew("assemble")`. Learn more
`gradle(vararg args: string)`	`Int`	Runs Gradle commands using Gradle from the container image. For example: `api.gradle("assemble")`
`dotnet(vararg args: string)`	`Int`	Not yet available Runs `dotnet` driver commands. For example, `api.dotnet("restore")`
`spaceUrl()`	`String`	Returns the URL of your Space instance.
`gitBranch()`	`String`	Returns the name of the current Git branch. For example, `if api.gitBranch().contains("dev")`
`gitRevision()`	`String`	Returns the current Git revision number. For example, `if api.gitRevision() == "..."`
`executionNumber()`	`String`	Returns the number of the current Automation script execution. You can use this number, for example, to generate the application version number.
`projectId()` and `projectKey()`	`String`	Returns the ID and the key of the current project.
`spaceClientId()` and `spaceClientSecret()`	`String`	Returns the current client ID and secret. These are temporary OAuth 2.0 credentials issued to the current script. The script uses them to authenticate in various Space modules. For example, you may need it to authenticate in a Packages repository in order to publish script artifacts.
`parameters()`	`String`	Lets you pass parameters between job steps. Learn more
`fileShare()`		Lets you share files between job steps. Learn more
`space()`		Lets you work with various Space modules. For example: `space().chats`: lets you send messages to Chats, `space().packages`: lets you work with package repositories in Packages, `space().projects`: lets you manage Projects, and so on. The Space modules API works through the Space HTTP API. In other words, `space()` is a Kotlin-based HTTP API client. Learn more Note that in the current Space version, some of these APIs might not be accessible from Automation scripts. This is a known issue related to the lack of permissions of the Automation service.

job.container.service

service runs a container with a network-accessible service. Learn more

service(image: String, init: Service.() -> Unit = {})

image: String is the name of an image on Docker Hub, in Space Packages, or in another repository.

init function configures the container and runs specified commands and scripts. You can use the following methods and properties inside init:

	`alias(alias: String)` specifies a network hostname for the container. If not specified, the hostname will be generated based on the `image` name.
	`user: String` specifies the user account that will be used to run commands and scripts inside the container.
	`args` provides arguments for a default image command or for `entrypoint`
	`entrypoint` overrides a default image command with the specified one
	`kotlinScript` runs Kotlin code
	`env` sets an environment variable in the container
	`resources` limits container resources (CPU and memory). Learn more about service resources

For example:

                job("ping") {
                    container(image = "alpine") {
                        // ping service 5 times
                        shellScript {
                            content = "ping -c 5 db"
                        }

                        service("mysql:5.7") {
                            alias("db")
                            env["MYSQL_ROOT_PASSWORD"] = "pwd1234"
                        }
                    }
                }
            

job.container.resources

resources limits the resources for a container. The default resources constraints are:

2 virtual CPUs
7800 MB memory

resources(init: ExplicitResources.() -> Unit)

init function specifies resources constraints. You can use the following properties inside init:

cpu: Any? limits computing power (in cpu units) Supports the cpu and .mcpu units. For example:

250.mcpu or 0.25.cpu for .25 vCPU
500.mcpu or 0.5.cpu for .5 vCPU
1000.mcpu or 1.cpu for 1 vCPU
and so on.

memory: Any? limits memory. Supports the mb and gb units for MB and GB. For example: 1024.mb or 1.gb.

For example:

                job("Example") {
                    container(image = "alpine") {
                        resources {
                            cpu = 1.cpu
                            memory = 2000.mb
                        }
                    }
                }
            

job.container.env

env lets you set environment variables in a container. Don't confuse container environment variables with Automation environment variables.

env = ProcessEnvironment()

The ProcessEnvironment class provides a single function for setting environment variables:

	`set(name: String, value: String)`

For example:

                job("Example") {
                    container(image = "alpine") {
                        env.set("SITE_URL", "staging.mysite.com")
                    }
                }
            

job.git

git lets you specify Git repository checkout options. There are two main use-cases of the git item:

Fetching additional branches and revisions: By default, Automation checks out only the current revision (the one that contains the currently running .space.kts script).
Checking out additional repositories in projects with multiple repositories: When the build script requires the source code from several repositories at once.

git(init: DefaultGitRepository.() -> Unit = {})

git(repositoryName: String, init: ExternalGitRepository.() -> Unit = {})

repository: String is the name of a Git repository. For the DefaultGitRepository (the one that contains the currently running .space.kts script), omit the repository argument. For example: git {...}

init function specifies the repository checkout options. You can use the following properties inside init:

	`cloneDir: String` specifies the checkout path for the repository relative to the `/mnt/space/work` directory. (Available only for `ExternalGitRepository`)
	`depth: Int` specifies the depth of the repository commit history (the number of the last commits that must be fetched). By default, `1`. To fetch all commits from the history, specify the `UNLIMITED_DEPTH` value.
	`refSpec: String` specifies the exact repository branch name, revision number, or Git refspec map format.

For example:

                job("git checkout") {
                    git {
                        // get all commits for the main repo
                        depth = UNLIMITED_DEPTH
                    }

                    // checkout repo-2 as well
                    git("repo-2") {
                        // put it inside /mnt/space/work/secondRepo
                        cloneDir = "secondRepo"
                        // fetch the new-feature branch (not check out!)
                        refSpec = "new-feature"
                    }

                    container(image = "alpine") {
                        shellScript {
                            content = """
                                echo Checked-out repos:
                                ls /mnt/space/work
                                echo Working dir:
                                pwd
                            """
                            // Checked-out repos:
                            // /mnt/space/work/main-project-repo
                            // /mnt/space/work/secondRepo
                            // Working dir:
                            // /mnt/space/work/main-project-repo
                        }
                    }
                }
            

job.parallel

By default, all container steps are executed sequentially inside a job. To execute them in parallel, put them inside a parallel block.

parallel(init: StepFork.() -> Unit)

	`init` function contains the `run` blocks that must be run in parallel. By using the `sequential` method of the `StepFork` class, you can execute `container` steps sequentially inside `parallel`.

For example:

                job("Example") {
                    // I run before others
                    container(displayName = "Step 1", image = "alpine") {
                        args("echo", "1")
                    }

                    parallel {
                        // I run after 'Step 1'
                        container(displayName = "Step 2", image = "alpine") {
                            args("echo", "2")
                        }
                        // I run along with 'Step 2'
                        container(displayName = "Step 3", image = "alpine") {
                            args("echo", "3")
                        }
                    }
                }
            

job.parallel.sequential

sequential executes container steps inside the parallel block sequentially.

sequential(init: StepSequence.() -> Unit)

	`init` function contains the `container` steps that must be run sequentially.

For example:

                job("Example") {
                    // I run before others
                    container(displayName = "Step 1", image = "alpine") {
                        args("echo", "1")
                    }

                    parallel {
                        // I run after 'Step 1'
                        container(displayName = "Step 2", image = "alpine") {
                            args("echo", "2")
                        }
                        sequential {
                            // I run along with 'Step 2'
                            container(displayName = "Step 3", image = "alpine") {
                                args("echo", "3")
                            }
                            // I run after 'Step 3' and along with 'Step 2'
                            container(displayName = "Step 4", image = "alpine") {
                                args("echo", "4")
                            }
                        }
                    }
                }
            

job.startOn

The startOn block contains events that trigger the job.

startOn(init: Triggers.() -> Unit)

init function sets the corresponding triggers using methods of the Triggers class:

	`gitPush`: the trigger is enabled by default
	`schedule`
	`gitBranchDeleted`
	`codeReviewOpened`
	`codeReviewClosed`

For example:

                job("example") {
                    startOn {
                        codeReviewOpened{}
                    }
                }
            

job.startOn.gitPush

gitPush runs the job after a commit is pushed to the project repository. By default, the gitPush trigger is enabled for a project. Important: Once you add any other trigger to the job, the gitPush trigger will be disabled.

gitPush(init: GitPushTrigger.() -> Unit)

init function configures the trigger. You can use the following properties inside init:

	`enabled: Boolean` enables/disables the trigger. `true` by default
	`branchFilter(filter: BranchFilter.() -> Unit)` specifies the filter by a branch name. Supports include (`+`) and exclude (`-`) rules, Kotlin regular expressions (`Regex`), and the asterisk (`*`) wildcards. Learn more
	`branchFilter: String` specifies the include filter by a branch name.
	`pathFilter(filter: PathFilter.() -> Unit)` specifies the filter by a certain directory or file name. Supports include (`+`) and exclude (`-`) rules, the asterisk (``) and double-asterisk (`*`) wildcards. Learn more
	`repository: String` specifies a project repository where a job must track changes. The job is started after changes are committed to the specified repository. Learn more

For example:

                job("example") {
                    startOn {
                        // Trigger job on changes in all 'release-*' branches
                        // excluding 'release-main'
                        // The changes must be only in 'src/mainModule/' and
                        // its subdirectories, but not in the 'myfile.kt' files
                        gitPush {
                            branchFilter {

                                +"refs/heads/release-*"
                                -Regex("release-main")
                            }

                            pathFilter {
                                +"src/mainModule/**"
                                -"**/myfile.kt"
                            }
                        }
                    }
                }
            

job.startOn.schedule

Runs the job on schedule. For example, once a day at a certain time (UTC timezone).

schedule(init: ScheduleTrigger.() -> Unit)

init function configures the trigger. You can use the following methods and properties inside init:

	`enabled: Boolean` enables/disables the trigger. `true` by default
	`cron(expression: String)` sets the trigger time (UTC) using the crontab format (MIN HOUR DAY MONTH DAYOFWEEK). You can specify more than one `cron` inside `schedule`.

For example:

                job("example") {
                    startOn {
                        // every day at 08 AM UTC
                        schedule { cron("0 8 * * *") }
                    }
                }
            

job.startOn.gitBranchDeleted

gitBranchDeleted runs the job when a git branch is deleted from the project repository.

gitBranchDeleted(init: GitBranchDeletedTrigger.() -> Unit = {})

init function configures the trigger. You can use the following properties inside init:

	`enabled: Boolean` enables/disables the trigger. `true` by default
	`branchFilter(filter: BranchFilter.() -> Unit)` specifies the filter by a branch name. Supports include (`+`) and exclude (`-`) rules, Kotlin regular expressions (`Regex`), and the asterisk (`*`) wildcards.
	`branchFilter: String` specifies the include filter by a branch name.

For example:

                job("example") {
                    startOn {
                        // name contains 'new-feature'
                        gitBranchDeleted {
                            branchFilter {
                                +Regex("new-feature")
                                -"refs/heads/my-new-feature"
                            }
                        }
                    }
                }
            

job.startOn.codeReviewOpened

codeReviewOpened runs the job when a code review is opened in the project.

codeReviewOpened(init: CodeReviewOpenedTrigger.() -> Unit = {})

init function configures the trigger. You can use the following properties inside init:

	`enabled: Boolean` enables/disables the trigger. `true` by default

For example:

                job("example") {
                    startOn {
                        codeReviewOpened{}
                    }
                }
            

job.startOn.codeReviewClosed

codeReviewClosed runs the job when a code review is closed in the project.

codeReviewClosed(init: CodeReviewClosedTrigger.() -> Unit = {})

init function configures the trigger. You can use the following properties inside init:

	`enabled: Boolean` enables/disables the trigger. `true` by default

For example:

                job("example") {
                    startOn {
                        codeReviewClosed{}
                    }
                }
            

job.failOn

The failOn block contains conditions under which a job will be considered failed. By default, failed tests and non-zero exit code are failure conditions.

failOn(init: FailureConditions.() -> Unit)

init function sets the corresponding failure conditions using methods of the FailureConditions class:

	`nonZeroExitCode`: default condition
	`testFailed`: default condition
	`outOfMemory`: default condition

                job("example") {
                    failOn {
                        testFailed { enabled = false }
                    }
                }
            

job.failOn.nonZeroExitCode

With nonZeroExitCode, the job is considered failed when it returns nonzero status code. It is a default failure condition.

nonZeroExitCode(init: NonZeroExitCodeCondition.() -> Unit)

init function configures the condition. You can use the following properties inside init:

	`enabled: Boolean` enables/disables the condition. `true` by default

                job("example") {
                    failOn {
                        // disable nonzero code condition
                        nonZeroExitCode { enabled = false }
                    }
                }
            

job.failOn.testFailed

With testFailed, the job is considered failed if at least one test fails during the job run. It is a default failure condition. Automation detects failed tests by parsing the job output. Currently, only Gradle test output is supported.

testFailed(init: TestFailedCondition.() -> Unit)

init function configures the condition. You can use the following properties inside init:

	`enabled: Boolean` enables/disables the condition. `true` by default

For example:

                job("example") {
                    failOn {
                        // disable testFailed condition
                        testFailed { enabled = false }
                    }
                }
            

job.failOn.outOfMemory

With outOfMemory, the job is considered failed if any of job containers runs out of memory (based on the OOMKilled event). It is a default failure condition.

outOfMemory(init: OutOfMemoryCondition.() -> Unit)

init function configures the condition. You can use the following properties inside init:

	`enabled: Boolean` enables/disables the condition. `true` by default

For example:

                job("example") {
                    failOn {
                        // disable outOfMemory condition
                        outOfMemory { enabled = false }
                    }
                }
            

job.failOn.timeOut

With timeOut, the job is considered failed if it runs longer than the specified time period. To specify time period, you should use the timeOutInMinutes keyword inside timeOut. The default and maximum allowed timeout is 120 minutes.

timeOut(init: TimeOutFailedCondition.() -> Unit)

init function configures the condition. You can use the following properties inside init:

	`enabled: Boolean` enables/disables the condition. `true` by default
	`timeOutInMinutes: Int` job timeout in minutes. `120` by default. Cannot be larger than `120`

For example:

                job("example") {
                    failOn {
                        // fail after 15 minutes
                        timeOut {
                            timeOutInMinutes = 15
                        }
                    }
                }
            

job.volumeSize

volumeSize sets the size of the disk mounted to a container. The disk contains project repository. By default, 5 GiBs. Supports the mb and gb units for MB and GB. For example, 10000.mb or 10.gb.

volumeSize: Any?

For example:

                job("example") {
                    // mount 10GB volume
                    volumeSize = 10.gb
                }
            

job.cloneRepository

cloneRepository specifies whether to clone the project repository to the disk that is mounted to containers. By default, true. If a job is not supposed to anyhow work with the project code, set cloneRepository = false. This will reduce the job run time.

cloneRepository: Boolean

For example:

                job("example") {
                    // do not clone the repo
                    cloneRepository = false
                }
            

job.docker

docker is a special helper item used to simplify building and publishing Docker images. Learn more

docker(init: DockerStep.() -> Unit)

init function lets you run docker build and docker publish commands:

beforeBuildScript(init: ProcessShellScript.() -> Unit) runs a shell script specified in init. The script is run before build. Uses /busybox/sh.

build(init: DockerBuild.() -> Unit) runs docker build with properties specified in init:

	`context: String?` sets a path to Docker context. By default, it's a working directory.
	`file: String?` sets a path to `Dockerfile`. By default, Automation will look for the file in the project root directory.
	`labels: DockerLabels` sets labels for the image. Use it as a string key-value storage: `labels["key"] = "value"`
	`args: DockerBuildArgs` sets build-time variables. Use it as a string key-value storage: `args["key"] = "value"`

push(name: String, init: (DockerPush.() -> Unit)? = null) runs docker push:

name: String sets an image name. Must include registry URL. For example: mycompany.registry.jetbrains.space/mydocker/myimage

init function lets you specify additional docker push settings:

	`tag: String?`, `tags(vararg tagNames: String)`, `tags(tagNames: Collection<String>)` sets image tags.

resources(init: ExplicitResources.() -> Unit) lets you specify container resources in the same way as job.container.resources

For example:

                job("Build and push Docker") {
                    container(displayName = "Build sources", image = "openjdk") {
                        shellScript {
                            content = """
                                ./gradlew build
                                cp output mnt/space/share
                            """
                        }
                    }

                    docker {
                        resources {
                            cpu = 1.cpu
                            memory = 2000.mb
                        }

                        beforeBuildScript {
                            content = "cp mnt/space/share docker"
                        }

                        build {
                            context = "docker"
                            file = "./docker/Dockerfile"
                            labels["vendor"] = "mycompany"
                            args["HTTP_PROXY"] = "http://10.20.30.2:1234"
                        }

                        push("mycompany.registry.jetbrains.space/mydocker/myimage") {
                            tags("version1.0", "stable")
                        }
                    }
                }
            

job.gradle

gradle is a special helper item that runs specified Gradle commands using Gradle installed in the container (specified in PATH). Use gradle to simplify your build scripts. Learn more

gradle(image: String? = null, vararg args: String, init: Project.Container.() -> Unit = {})

	`image: String?` is the name of an image on Docker Hub, in Space Packages, or in another repository. The image must include Gradle installation. If not specified, `gradle:latest` is used.
	`args: String` specifies arguments for 'gradle'
	`init` runs specified commands and scripts after the 'gradle' command is run

For example:

                job("Example") {
                    // run 'gradle build'
                    gradle(null, "build")
                }
            

job.gradlew

gradlew is a special helper item that runs Gradle commands using Gradle wrapper from the project directory. Use gradlew to simplify your build scripts. Learn more

gradlew(image: String? = null, vararg args: String, init: Project.Container.() -> Unit = {})

	`image: String?` is the name of an image on Docker Hub, in Space Packages, or in another repository. The image must include JRE/JDK 9 or later. If not specified, `openjdk:latest` is used.
	`args: String` specifies arguments for 'gradlew'
	`init` runs specified commands and scripts after the 'gradlew' command is run

For example:

                job("Example") {
                    // run 'gradlew build'
                    gradlew(null, "build")
                }
            

Last modified: 21 July 2021