Skip to content

Docker

class Docker

Integrate Docker into your build.

This plugin is responsible for adding the docker extension to scripts:

val dockerBuild by job {
    useDockerInDocker()
    useContainerRegistry()

    script {
        docker.build("backend")
    }
}

This plugin uses Docker in Docker, which can create security vulnerabilities. To build containers without using Docker in Docker, see the Kaniko plugin.

Job extensions

This plugin provides the following job extensions:

Types

Companion

object Companion

Functions

build

fun build(
    image: String, 
    version: String = defaultVersion, 
    dockerfile: String = "Dockerfile", 
    context: String = ".", 
    previousVersions: List<String> = listOf("latest")
)

Builds a Docker image from a Dockerfile.

The image will be built but not published anywhere, remember to call push after building it.

The images built by this function have the BuildKit Inline Cache enabled, and can therefore be used as caching for future builds.

Parameters

  • image: The name of the image that will be built (e.g. "backend").

  • version: The version which will be assigned to the built image. By default, the version number is created from the pipeline identifier, to ensure two pipelines do not overwrite each other.

  • dockerfile: The path to the Dockerfile, relative to the current working directory.

  • context: The path of the directory in which the build takes place, relative to the current working directory. The files in this directory will be available in the Dockerfile's COPY instruction.

  • previousVersions: Version names of previous versions that are candidate for caching. If Docker finds identical layers in these images from what is currently being built, it will reuse the existing layers, greatly speeding the build. Note that for Docker to use an image as a cache layer, it must have caching enabled.

Samples

opensavvy.gitlab.ci.plugins.DockerTest.buildImage

logInToRegistry

fun logInToRegistry(
    registry: String, 
    username: String, 
    password: String
)

Logs in to an arbitrary container registry.

To log in to the GitLab container registry of the current project, use useContainerRegistry instead.

Parameters

  • registry: The URL of the registry to log in to.

  • username: The username used to log in to registry.

  • password: The password used to log in to registry.

pull

fun pull(
    image: String, 
    version: String = "latest", 
    allowFailure: Boolean = false
)

Pulls a given image's version.

Note that pulling a previous version of an image before building a new version is useless: Docker's cache is able to reuse layers without pulling the image.

Parameters

  • image: The name of the image to pull (e.g. "alpine", "curlimages/curl").

  • version: The version to pull (e.g. "edge").

  • allowFailure: If set to true, failing to pull the image will be ignored, and will not fail the current job.

push

fun push(image: String, version: String = defaultVersion)

Pushes the image to a container registry.

Before pushing to a container registry, you may want to logInToRegistry.

Parameters

  • image: The name of the image that will be pushed (e.g. "backend"). The image must exist locally.

  • version: The version of the image to push. The default version number for this command is the same as the build command's, making it easy to use them together.

Samples

opensavvy.gitlab.ci.plugins.DockerTest.buildImage

rename

fun rename(
    image: String, 
    oldVersion: String = defaultVersion, 
    newVersion: String = "latest"
)

Renames a version of an image.

This command pulls the image for the version oldVersion, renames it to newVersion, then finally pushes it back.

Parameters

  • image: The name of the image that will be renamed (e.g. "backend").

  • oldVersion: The version that will be renamed. The default version number for this command is the same as the build command's, making it easy to use them together.

  • newVersion: The new name of the version.

Samples

opensavvy.gitlab.ci.plugins.DockerTest.buildImage