Space Automation automation Help

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)

Propertyname: String is the name of the job
Methodinit is the job content

For example:

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

job.container

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

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

Property

image: String is the name of an image on

  • Docker Hub. An image name is enough, for example: container("alpine:latest")

  • Space Packages. A full image URL is required, for example: container("mycompany.registry.jetbrains.space/p/mpj/mydocker/myimage")

Method

init function configures the container and runs specified commands and scripts using the methods and properties of the Container class:

PropertymountDir: String sets the absolute path to the directory where the Automation volume must be mounted. By default, /mnt/space. The volume contains the project sources (/mnt/space/work) and various Automation data (/mnt/space/system).
PropertyworkDir: String sets the absolute or relative 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. The relative path is set relative to mountDir.
Propertyuser: String specifies the user account that will be used to run commands and scripts inside the container.
Methodargs provides arguments for a default image command or for entrypoint
Methodentrypoint overrides a default image command with the specified one
MethodshellScript runs the specified shell script
MethodkotlinScript runs Kotlin code
Methodservice runs a container with a network-accessible service, for example, a database server
Propertyenv sets an environment variable in the container
Methodresources limits container resources (CPU and memory)

For example:

job("Example") { // in the container with 'gradle' image container("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("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("myImage") { entrypoint("/bin/sh") args("echo", "Hello World!") } }

job.container.shellScript

shellScript runs the provided shell script.

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

Method

init function specifies the script and script interpreter using the properties of the ProcessShellScript class:

Property

interpreter: String specifies the interpreter used to run the script. By default, /bin/sh.

Propertycontent: String? specifies the shell script content. This can be a multiline string.
Propertylocation: String? specifies a path to the shell script file. This may be an absolute path or a path relative to workDir.

For example:

job("Example shell scripts") { container("ubuntu") { shellScript { interpreter = "/bin/bash" content = """ echo 'echo Hello World!' > /mnt/space/share/myscript.sh chmod +x /mnt/space/share/myscript.sh """ } } container("ubuntu") { shellScript { location = "/mnt/space/share/myscript.sh" } } // In job logs, we'll see 'Hello World!' }

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 8 or later.

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

For example:

job("Example kotlin script") { container("openjdk:11") { kotlinScript { api -> if (api.gitBranch() == "refs/heads/master") { println("Running in master branch") } else { println("Running in custom branch") } } } }
job("Example script") { container("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:

FunctionReturnsDescription
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().blogs: lets you create, edit, delete articles in Blogs,

  • 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. To see the full list of modules and commands available through the modules API, on the navigation bar, click administration.png Administration and choose HTTP API Playground.

job.container.service

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

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

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

init function configures the container and runs specified commands and scripts using the methods and properties of the Service class:

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

For example:

job("ping") { container("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 vCPU (virtual CPU)

  • 7800 MiB memory

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

Method

init function specifies resources constraints using the properties of the ExplicitResources class:

Property

cpu: Int limits computing power (in cpu units):

  • 256 for .25 vCPU

  • 512 for .5 vCPU

  • 1024 for 1 vCPU

  • and so on.

Propertymemory: Int limits memory (in MiBs)

For example:

job("Example") { container("alpine") { resources { cpu = 1024 memory = 2000 } } }

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:

Methodset(name: String, value: String)

For example:

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

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)

Methodinit 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") { // 1. I run before others container("alpine") { args("echo", "1") } parallel { // 2. I run after 1 container("alpine") { args("echo", "2") } // 3. I run along with 2 container("alpine") { args("echo", "3") } } }

job.parallel.sequential

sequential executes container steps inside the parallel block sequentially.

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

Methodinit function contains the container steps that must be run sequentially.

For example:

job("Example") { // 1. I run before others container("alpine") { args("echo", "1") } parallel { // 2. I run after 1 container("alpine") { args("echo", "2") } sequential { // 3. I run along with 2 container("alpine") { args("echo", "3") } // 4. I run after 3 and along with 2 container("alpine") { args("echo", "4") } } } }

job.startOn

The startOn block contains events that trigger the job .

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

Method

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

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.

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

Method

init function configures the trigger using properties of the GitPushTrigger class:

Propertyenabled: Boolean enables/disables the trigger. true by default

For example:

job("example") { startOn { // disable the default gitPush trigger gitPush { enabled = false } } }

job.startOn.schedule

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

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

Method

init function configures the trigger using properties and methods of the ScheduleTrigger class:

Propertyenabled: Boolean enables/disables the trigger. true by default
Methodcron(expression: String) sets the trigger time (UTC timezone) 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 = {})

Method

init function configures the trigger using properties of the GitBranchDeletedTrigger class:

Propertyenabled: Boolean enables/disables the trigger. true by default
PropertybranchFilter: String specifies the regex pattern for the branch name

For example:

job("example") { startOn { { // name contains 'new-feature' gitBranchDeleted { branchFilter = "\bnew-feature\b" } } } }

job.startOn.codeReviewOpened

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

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

Method

init function configures the trigger using properties of the CodeReviewOpenedTrigger class:

Propertyenabled: 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 = {})

Method

init function configures the trigger using properties of the CodeReviewClosedTrigger class:

Propertyenabled: 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)

Method

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

MethodnonZeroExitCode : default condition
MethodtestFailed : default condition
MethodoutOfMemory : 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)

Method

init function configures the condition using properties of the NonZeroExitCodeCondition class:

Propertyenabled: 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 execution. It is a default failure condition.

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

Method

init function configures the condition using properties of the TestFailedCondition class:

Propertyenabled: 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)

Method

init function configures the condition using properties of the OutOfMemoryCondition class:

Propertyenabled: Boolean enables/disables the condition. true by default

For example:

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

job.volumeSize

volumeSize sets the size of the disk (in GiBs) mounted to a container. The disk contains project repository. By default, 5 GiBs.

volumeSize: Int

For example:

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

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 execution 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)

Method

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

MethodbeforeBuildScript(init: ProcessShellScript.() -> Unit) runs a shell script specified in init. The script is run before build.
Method

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

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

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

Propertyname: String sets an image name. Must include registry URL. For example: mycompany.registry.jetbrains.space/mydocker/myimage
Methodinit function lets you specify additional docker push settings:
Propertytag: String? sets an image tag.

For example:

job("Build and push Docker") { container("openjdk") { shellScript { content = """ ./gradlew build cp output mnt/space/share """ } } docker { 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") { tag = "version1.0" } } }

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 = {})

Propertyimage: String? is the name of an image on Docker Hub, in Space Packages, or in another repository. Must contain Gradle! If null, gradle:latest is used.
Propertyargs: String specifies arguments for 'gradle'
Method

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 = {})

Propertyimage: String? is the name of an image on Docker Hub, in Space Packages, or in another repository. Must contain JRE/JDK! If null, openjdk:latest is used.
Propertyargs: String specifies arguments for 'gradlew'
Method

init runs specified commands and scripts after the 'gradlew' command is run

For example:

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

Last modified: 27 July 2020