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

Official documentation

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

Official documentation

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

Official documentation

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

Official documentation

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

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

Official documentation.

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

Official documentation

`publishChangelogToDiscord`¶

fun Job.publishChangelogToDiscord()

`publishChangelogToTelegram`¶

fun Job.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

Official documentation

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

Official documentation.

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

Official documentation.

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

Official documentation.

toYaml¶

open override fun toYaml(): Yaml

Converts this object into a Yaml object.

`useContainerRegistry`¶

fun Job.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

Official documentation

See also

Variable: Access predefined CI/CD variables.

Job¶

Types¶

Companion¶

Properties¶

name¶

stage¶

Functions¶

afterScript¶

allowFailure¶

artifacts¶

beforeScript¶

cache¶

coverage¶

dependsOn¶

environment¶

image¶

interruptible¶

publishChangelogToDiscord¶

publishChangelogToTelegram¶

retry¶

script¶

service¶

tag¶

toYaml¶

useContainerRegistry¶

useDockerInDocker¶

useGradle¶

variable¶

`Companion`¶

`publishChangelogToDiscord`¶

`publishChangelogToTelegram`¶

`useContainerRegistry`¶

`useDockerInDocker`¶

`useGradle`¶