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.
init function specifies requirements to the host machine:
workerPool: String?: explicitly specify the desired run environment:
WorkerPools.SPACE_CLOUD or "space-cloud" for Space Automation Cloud.
WorkerPools.SELF_HOSTED or "self-hosted.default" for self-hosted workers.
If specified, overrides the Default worker pool parameter.
workerType: String?: explicitly specify the desired worker instance:
WorkerTypes.SPACE_CLOUD_UBUNTU_LTS_REGULAR or "space-cloud.ubuntu-lts.regular" (default)
WorkerTypes.SPACE_CLOUD_UBUNTU_LTS_LARGE or "space-cloud.ubuntu-lts.large"
If specified, overrides the Default worker pool parameter.
workerTags: choose the suitable run environment by user-created worker tags
resources: choose the suitable run environment by resources (CPU cores and RAM) available on the host machine
For example:
job("Example") {
host("Run it on macOS") {
shellScript {
location = "./myscript.sh"
}
requirements {
os { type = OSType.Mac }
}
}
}
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.
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.
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!")
}
}
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.
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
job.container.requirements
requirements specifies requirements to the host machine that should be used to run the step. Specify requirements in case you want to run a job with a container step not in the Space cloud but on a specific worker. Learn more
env lets you set environment variables in a container. Note that you can get various information about the current run context with the help of Automation environment variables.
env = Environment()
The Environment class provides a single function for setting environment variables:
env sets an environment variable on the host machine
requirements specifies requirements to a self-hosted worker. Only the worker that meets the requirements can run the job with this host step. Learn more
For example:
job("Example") {
host("Run build") {
// run msbuild
shellScript {
content = """
C:\"Program Files (x86)"\MSBuild\14.0\Bin\MsBuild.exe MySolution.sln
"""
}
// on any worker with Windows
requirements {
type = OSType.Windows
}
}
}
displayName: String? specifies the step name that will be displayed in job logs.
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. If null, the default interpreter will be used:
/bin/sh on Linux and macOS
cmd on Windows
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("Job with host and container") {
host("Prepare myscript.sh") {
shellScript {
interpreter = "/bin/bash"
content = """
echo Username: $1' >> ../../share/myscript.sh
echo Password: $2' >> ../../share/myscript.sh
chmod +x ../../share/myscript.sh
"""
}
}
// it's fine to use both 'host' and 'container' in one job
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("Example Kotlin script") {
host {
kotlinScript { api ->
if (api.gitBranch() == "refs/heads/main") {
println("Running in main branch")
} else {
println("Running in custom branch")
}
}
}
}
job("Example Kotlin script") {
host {
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. For the full list of available APIs, refer to job.container.kotlinScript
job.host.env
env lets you set environment variables on the host machine. Note that you can get various information about the current run context with the help of Automation environment variables.
env = Environment()
The Environment class provides a single function for setting environment variables:
set(name: String, value: String)
For example:
job("Example") {
container(image = "alpine") {
// one way to set env var
env.set("SITE_URL", "staging.mysite.com")
// another way to set env var
env["USERNAME"] = "anna"
}
}
job.host.requirements
requirements specifies requirements to the host machine that should be used to run the step. Learn more
init function specifies requirements to the host machine:
workerTags: choose the suitable worker by user-created tags
os: choose the suitable worker by the operating system of the host machine
resources: choose the suitable worker by resources (CPU cores and RAM) available on the host machine
For example:
job("Example") {
host("Run it on macOS") {
shellScript {
location = "./myscript.sh"
}
requirements {
os { type = OSType.Mac }
}
}
}
job.host.requirements.workerTags
workerTags specifies the required tag(s). Automation will route the job only to the worker that is marked with the specified tag(s). Learn more
workerTags(vararg tags: String)
For example:
job("Example") {
host("Run it on machines from pool-1 and pool-2") {
shellScript {
location = "./myscript.sh"
}
requirements {
workerTags("pool-1", "pool-2")
}
}
}
job.host.requirements.os
os specifies the required operating system. Automation will route the job only to the worker with the specified operating system. Learn more
os(configure: OSRequirementsBuilder.() -> Unit)
configure function specifies requirements to the operating system:
type: OSType? specifies the required OS type. Possible values:
OSType.Linux
OSType.Mac
OSType.Windows
name: String? specifies the required OS name
version: String? specifies the required OS version
arch: String? specifies the required OS architecture. For example, x86 or amd64
For example:
job("Example") {
host("Run it on Ubuntu") {
shellScript {
location = "./myscript.sh"
}
requirements {
os {
type = OSType.Linux
version = "ubuntu-20.02"
arch = "x86_64"
}
// run on Linux Mint
// os {
// name = "Linux Mint"
// arch = "x86"
// }
}
}
}
job.host.requirements.resources
resources specifies requirements to the available system resources (CPU cores and RAM) on the host machine. Automation will route the job only to the worker with the sufficient resources. Learn more
configure function specifies requirements to the available system resources:
minCpu: MilliCpu? specifies the required number of CPU cores in milliCPU. For example, to require 2 CPU cores, set minCpu = 2000. Otherwise, you can explicitly specify the measurement units: mcpu for milliCPU or cpu for CPU. For example, minCpu = 2.cpu
minMemory: Capacity? specifies the required amount of RAM in MB. For example, to require 1024MB, set minMemory = 1024. Otherwise, you can explicitly specify the measurement units: kb, mb, or gb. For example, minMemory = 1.gb
Fetching additional branches and revisions: By default, Automation checks out only the current revision (the one that contains the currently running .space.kts script).
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 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.
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:
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
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.
With timeOut, the job is considered failed if it cannot start within the specified time period or runs longer than the specified time period. To specify the timeouts 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
runningTimeOutInMinutes: Int or timeOutInMinutes (Deprecated) defines how much time in minutes the job is allowed to run. After the timeout expires, the job is considered failed. 120 by default. Cannot be larger than 120
waitingToStartTimeOutInMinutes: Int defines how much time in minutes the job can spend in the pending state before the actual run. There is a number of reasons for the pending state, for example, the amount of already running jobs available for your subscription plan has reached the limit, there are no available machines in the cloud pool, and so on. 60 by default. Cannot be larger than 60
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:
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 string key-value storage: labels["key"] = "value"
args: DockerBuildArgs sets build-time variables. Use it as string key-value storage: args["key"] = "value"
customPlatform: String? lets you build an image with another default platform, for example linux/arm64. See the list of possible values. This option is a counterpart of the customPlatform Kaniko option. You can also specify a CPU variant by adding it as a third parameter, for example, "linux/arm/v5". Currently, CPU variants are only known to be used for the ARM architecture as listed here. The resulting images cannot provide any metadata about CPU variant due to limitations of the OCI-ima ge specification.
Important: A worker that runs the job may not support the specified platform.
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
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
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")
}
ide: Ide specifies an IDE for remote development. During the warm-up, Space builds project indexes in the format compatible with the specified IDE. Can be: Ide.Fleet, Ide.Idea, Ide.CLion, Ide.GoLand, Ide.PhpStorm, Ide.PyCharm, Ide.RubyMine, Ide.WebStorm, and Ide.Rider.
profileId: String? (Optional) is a warm-up data identifier. You can use it to distinguish different warm-up data in the Space UI. Currently, not available.
init function lets you run warm-up scripts on specific Automation workers:
devfile: String? specifies the path to the project's devfile. To prepare the warm-up data, the job will run in a container based on the image specified in the devfile. Learn more
ideVersion: IdeVersion? (Optional) specifies the IDE version Space must build indexes for. ideVersion overrides the default IDE version. Possible usage:
ideVersion = IdeVersion.Specific("2022.1", "Stable"): for a specific version.
ideVersion = IdeVersion.LatestOfQuality("EAP1"): for a specific release state.
requirements(init: HostRequirementsBuilder.() -> Unit) specifies requirements to the host machine that should be used to run the warm-up script. Learn more
scriptLocation: String? specifies the path to a warm-up script. The script must be a .sh file.
For example:
job("Prepare data and build indexes for IDEA") {
warmup(ide = Ide.Idea) {
scriptLocation = "./dev-env-warmup.sh"
devfile = "./devfile.yaml"
}
}
job.warmup.env
env lets you set environment variables in a dev environment container. Note that you can get various information about the current run context with the help of Automation environment variables.
env = Environment()
The Environment class provides a single function for setting environment variables:
set(name: String, value: String)
For example:
job("My project warmup data") {
warmup(ide = Ide.Fleet, profileId = "fleet") {
// some env var that may be needed for the script
env["USERNAME"] = "SpaceUser"
requirements {
workerTags("fleet")
}
scriptLocation = "./dev-env-warmup.sh"
}
}
