opensavvy.gitlab.ci

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

AllowFailure

class AllowFailure : YamlExport

Configuration for job failure tolerance.

Artifacts

class Artifacts : YamlExport

Configures job artifacts that are attached to the job when it succeeds, fails, or always.

Cache

class Cache : YamlExport

ContainerImage

open class ContainerImage : YamlExport

ContainerService

class ContainerService : ContainerImage

Depends

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

Environment

class Environment : YamlExport

Declares which environment this job interacts with.

GitLabCi

class GitLabCi : YamlExport

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

enum RetryCause : YamlExport, Enum<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 : YamlExport, Enum<When> 

YamlExport

interface YamlExport

Objects that can be converted to Yaml.

Functions

gitlabCi

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

Convenience factory function for GitLabCi.