Skip to content

Job

class Job : YamlExport

A single execution step in a pipeline.

Jobs are instantiated using the job factory. See its documentation for more information.

Types

Companion

object Companion

Properties

name

val name: String

The name of this job, as it appears in the GitLab UI.

stage

val stage: Stage?

The Stage this job is a part of.

Stages are a simple way to group jobs and execution order. However, jobs can ignore this order, for example by using dependsOn.

If set to null, see the official documentation.

Functions

afterScript

fun afterScript(block: CommandDsl.() -> Unit)

Adds commands to execute after the main script of this job.

afterScript has the same syntax as script.

The main usage of afterScript is the ability to declare a script that will execute after all script calls, even those that haven't happened yet.

Example
val test by job {
    script {
        shell("make")
    }

    afterScript {
        // Something that executes after all scripts
    }
}
External resources

Read more about the differences between script and afterScript in the GitLab documentation.

allowFailure

fun allowFailure(enabled: Boolean)

Use allowFailure to determine whether a pipeline should continue running when a job fails.

To let the pipeline continue running subsequent jobs, use allowFailure(true). To stop the pipeline from running subsequent jobs, use allowFailure(false) (this is the default).

Example
val test by job {
    allowFailure(true)
}
External resources
fun allowFailure(configuration: AllowFailure.() -> Unit)

Use allowFailure to determine whether a pipeline should continue running when a job fails.

This variant allows specifying which exit codes are allowed to fail.

Example
val test by job {
    allowFailure {
        onExitCode(137)
    }
}
External resources

artifacts

fun artifacts(configuration: Artifacts.() -> Unit)

Declares paths that will be saved at the end of the job, and can later be consumed by other jobs in the same pipeline.

To learn more about configuring artifacts, see Artifacts.

Example
val test by job {
    script {
        shell("echo '1.1' >> version.txt")
    }

    artifacts {
        include("version.txt")
    }
}
External resources

beforeScript

fun beforeScript(block: CommandDsl.() -> Unit)

Adds commands to execute before the main script of this job.

beforeScript has the same syntax as script.

The main usage of beforeScript is the ability to declare a script that will execute before all already-registered calls to script.

Example
val test by job {
    beforeScript {
        shell("apt upgrade")
    }

    script {
        shell("echo Hello world")
    }
}
External resources

Read more about the differences between script and beforeScript in the GitLab documentation.

cache

fun cache(configuration: Cache.() -> Unit)

Declares paths that will be reused between different jobs, even if they are of different pipelines.

Note that this is very easy to misuse in ways that make the pipeline less reliable or slower. In particular, avoid caching node_modules or ~/.gradle or other dependency download caches if you're using GitLab Shared Runners, as downloading the cached dependencies can easily become slower than downloading the dependencies themselves.

Instead, use systems like Gradle's remote build cache, GitLab's dependency proxy.

To learn more about configuring the cache, see Cache.

Example
val test by job {
    cache {
        include(".gradle/wrapper")
        keyFile("gradle/wrapper/gradle-wrapper.properties")
    }

    script {
        echo("./gradlew test")
    }
}

This particular example is inspired by the Gradle plugin, which we recommend instead of implementing this manually.

External resources

coverage

fun coverage(regex: String)

Declares a regular expression to configure how code coverage is extracted from the job output. The coverage is shown in the UI if at least one line of the job output matches regex.

Example
val test by job {
    script {
        shell("echo Code coverage: 99%")
    }

    coverage("Code coverage: \d+(?:\.\d+)?")
}
External resources

dependsOn

fun dependsOn(
    job: Job, 
    artifacts: Boolean = false, 
    optional: Boolean = false
)

This job will wait until job has terminated.

By default, jobs start immediately.

Example
gitlabCi {
    val compile by job {
        script {
            shell("make")
        }

        artifacts {
            include("output")
        }
    }

    val test by job {
        dependsOn(compile, artifacts = true)

        script {
            shell("make test")
        }
    }
}.println()
Official documentation

Parameters

  • artifacts: If set to true, the artifacts generated by job will be downloaded before the current job starts.

  • optional: If set to true, the job will run even if job was excluded from this pipeline (using rules, only or when).

environment

fun environment(configuration: Environment.() -> Unit)

Tells GitLab about a service deployed by this job, so it can appear in the UI.

Example
val deploy-qa by job {
    script {
        // …
    }

    environment {
        name("qa")
        url("https://qa.your.app/dashboard")
    }
}
External resources

image

fun image(
    name: String, 
    version: String? = null, 
    configuration: ContainerImage.() -> Unit = {}
)

The container image used to execute this job.

Example
val ubuntu by job {
    image("ubuntu")

    script {
        shell("echo 'Hello world!'")
    }
}

In this example, the runner will download the latest Ubuntu image and run the bash script that prints Hello world!.

External resources

interruptible

fun interruptible(bool: Boolean)

Determines whether this job can be safely canceled after it has started.

If set to true, if a new commit is pushed to the same branch, this job will be canceled.

If set to false (the default), if a new commit is pushed to the same branch, the job and any later jobs in the pipeline will continue executing.

External resources

publishChangelogToDiscord

publishChangelogToTelegram

retry

fun retry(max: Int, configuration: Retry.() -> Unit = {})

Configures how many times a job is retried if it fails. If not defined, defaults to 0 and jobs do not retry.

Example
val test by job {
    retry(2) {
        whenType(RetryWhen.RunnerSystemFailure)
        onExitCode(137)
    }
}
External resources

script

fun script(block: CommandDsl.() -> Unit)

Adds commands to execute in this job.

Example
val test by job {
    script {
        shell("echo Hello World")
    }

    script {
        shell("echo You can call 'script' multiple times")
        shell("echo or add multiple commands inside a single 'script' call")
    }
}

Calling script multiple times executes the commands after the previous ones (the execution happens in the same order as in the source code).

See CommandDsl to see what functions are available in script.

External resources

service

fun service(
    name: String, 
    version: String? = null, 
    configuration: ContainerService.() -> Unit = {}
)

Additional container images used by this job.

Example
val docker by job {
    image("docker")
    service("docker", version = "dind")
}
External resources

tag

fun tag(name: String)

Adds a tag to this job.

Only runners that possess the same tag(s) will be able to execute this job.

Example

To run a job only on runners that are configured with the tags ArchLinux and Docker:

val test by job {
   tag("archlinux")
   tag("docker")

   script { … }
}

The tags themselves do not have any special meaning, though official GitLab Runners use a few standard ones. Each official runner is listed with its tags in the project settings' runner list.

External resources

toYaml

open override fun toYaml(): Yaml

Converts this object into a Yaml object.

useContainerRegistry

Logs in the current job to the GitLab Container Registry.

useDockerInDocker

fun Job.useDockerInDocker(dockerVersion: String = "20.10", dockerInDockerVersion: String = "-dind")

Configures the current job to use the docker command using Docker In Docker.

useGradle

fun Job.useGradle()

Enables the Gradle plugin.

variable

fun variable(name: String, value: String)

Declares an environment variable that will be available for the entire length of the job.

Example
val test by job {
    variable("version", "1.0")

    script {
        shell("echo \$version")
    }
}
External resources

See also

  • Variable: Access predefined CI/CD variables.