Skip to content

GitLab CI Kotlin DSL • opensavvy.gitlab.ci

Package-level declarations

Jobs, stages, dependencies and more: declaring a GitLab CI pipeline from Kotlin.

Most of the objects are identical, or very similar, to their equivalent in the Yaml format. Some have been renamed or restructured for readability.

Overview

A pipeline is created by the gitlabCi function. It can be converted to Yaml by calling its println function:

gitlabCi {
    // Declare your pipeline here
}.println()

A pipeline is composed of stages, themselves composed of jobs. Each job is a unit of work, which will be executed independently by GitLab. A job can do anything that you can write a program for. Most commonly, jobs use Docker images to provide a ready-to-use environment.

gitlabCi {
    // Create two stages: test and deploy
    val test by stage()
    val deploy by stage()

    // First job to test our app
    val build by job(stage = test) {
        image("ubuntu")

        script {
            shell("make")
        }

        artifacts {
            // The 'build' directory will be stored when the job is over
            include("build")
        }
    }

    if (Value.isDefaultBranch) {
        val publish by job(stage = deploy) {
            image("ubuntu")

            // Wait for 'build' to finish before starting,
            // and download the artifacts it generated
            dependsOn(build, artifacts = true)

            script {
                // Add your own logic
            }
        }
    }
}.println()

Reading order

Start with gitlabCi, stages and jobs.

Types

Artifacts

Cache

class Cache : YamlExport

ContainerImage

open class ContainerImage : YamlExport

ContainerService

Depends

data class Depends(val job: Job, val artifacts: Boolean, val optional: Boolean) : YamlExport

GitLabCi

Entrypoint to the GitLab CI pipeline generation.

GitLabCiDsl

@DslMarker
annotation class GitLabCiDsl

Marker for APIs that are part of the GitLab CI DSL.

Job

class Job : YamlExport

A single execution step in a pipeline.

Retry

class Retry : YamlExport

Configuration for job retry behavior.

RetryCause

Failure types that can be used with Retry.on.

Stage

data class Stage(val name: String)

A stage in a pipeline.

Value

object Value

Variable

object Variable

Predefined variables in GitLab CI.

When

enum When : Enum<When> , YamlExport

YamlExport

interface YamlExport

Objects that can be converted to Yaml.

Functions

gitlabCi

fun gitlabCi(block: GitLabCi.() -> Unit):

Convenience factory function for GitLabCi.

job

fun GitLabCi.job(name: String, stage: Stage? = null, block: Job.() -> Unit):

Declares a new Job in the current pipeline.

fun GitLabCi.job(name: String? = null, stage: Stage? = null, block: Job.() -> Unit = {}):

Declares a new Job in the current pipeline.

stage

fun GitLabCi.stage(name: String): Stage

Creates a stage with a given name.

Creates a stage automatically named after the variable it is assigned to.