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.container
container
runs a container and executes the specified command or script inside this container.
container(image: String, init: Container.() -> Unit = {})
![]() |
| ||||||||||||||||||||
![]() |
|
For example:
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.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.container.shellScript
shellScript
runs the provided shell script.
shellScript(init: ProcessShellScript.() -> Unit)
|
For example:
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:
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 |
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:
The Space modules API works through the Space HTTP API. In other words, |
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. | ||||||||||||||
![]() |
|
For example:
job.container.resources
resources
limits the resources for a container. The default resources constraints are:
2 virtual CPUs
7800 MiB memory (approx. 8 GB)
resources(init: ExplicitResources.() -> Unit)
|
For example:
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
|
For example:
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
).Checking out other 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 ), omit the repository argument. For example: git {...} | ||||||
![]() |
|
For example:
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.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.startOn
The startOn
block contains events that trigger the job
.
startOn(init: Triggers.() -> Unit)
![]() |
|
For example:
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)
![]() |
|
For example:
job.startOn.schedule
Runs the job on schedule
. For example, once a day at a certain time (UTC timezone).
schedule(init: ScheduleTrigger.() -> Unit)
![]() |
|
For example:
job.startOn.gitBranchDeleted
gitBranchDeleted
runs the job when a git branch is deleted from the project repository.
gitBranchDeleted(init: GitBranchDeletedTrigger.() -> Unit = {})
![]() |
|
For example:
job.startOn.codeReviewOpened
codeReviewOpened
runs the job when a code review is opened in the project.
codeReviewOpened(init: CodeReviewOpenedTrigger.() -> Unit = {})
![]() |
|
For example:
job.startOn.codeReviewClosed
codeReviewClosed
runs the job when a code review is closed in the project.
codeReviewClosed(init: CodeReviewClosedTrigger.() -> Unit = {})
![]() |
|
For example:
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)
![]() |
|
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)
![]() |
|
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.
testFailed(init: TestFailedCondition.() -> Unit)
![]() |
|
For example:
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)
![]() |
|
For example:
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)
![]() |
|
For example:
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.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.docker
docker
is a special helper item used to simplify building and publishing Docker images. Learn more
docker(init: DockerStep.() -> Unit)
![]() |
|
For example:
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. Must contain Gradle! If null , gradle:latest is used. |
![]() | args: String specifies arguments for 'gradle' |
![]() |
|
For example:
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. Must contain JRE/JDK! If null , openjdk:latest is used. |
![]() | args: String specifies arguments for 'gradlew' |
![]() |
|
For example: