palantir/gradle-docker: a Gradle plugin set that builds and pushes container images

Three plugins aimed at one Gradle build pipeline

Palantir publishes three Gradle plugins under one project, and together they solve a narrow problem: a JVM build that has to emit a container image without leaving Gradle. The `com.palantir.docker` plugin adds tasks for building and pushing images from a simple configuration block. The `com.palantir.docker-compose` plugin adds a task that populates placeholders in a docker-compose template file with image versions resolved from dependencies. The `com.palantir.docker-run` plugin adds tasks for starting, stopping, statusing and cleaning up a named container built from a specified image.

The audience is teams whose services are already produced by Gradle and whose CI job would otherwise shell out to `docker build` and `docker push`. Running Docker from a script is easy. Knowing which files a Gradle task produced, and putting those files into the build context without the developer listing them a second time, is the part this project actually contributes. That is also where its sharpest edges sit, because the configuration is a Groovy DSL that has accumulated a decade of options.

The docker block turns Gradle task outputs into a build context

The `docker` extension is the whole configuration surface of the main plugin. `name` sets the image name and may include a tag. `dockerfile` selects the file to build from and defaults to `project.file('Dockerfile')`, and it has to be a file object rather than a path string. `files` is the option that carries the real value: it is evaluated per `Project#files`, so a task output collection such as `tasks.distTar.outputs` can be passed directly and the plugin adds those outputs to the Docker build context automatically. The underlying CopySpec is also reachable, which is how a directory of sources is copied into the context.

docker {
    files tasks.distTar.outputs, 'my-file.txt'
    copySpec.from("src/myDir").into("myDir")
}

Read that snippet literally. The first line adds the archive produced by a distribution task and one extra text file from the project root. The second line pulls everything under `src/myDir` into the same collection and places it in a `myDir` directory of the build context. The documented result is a `build/docker/` directory holding the copied directory, the text file and the contents of the task outputs together, which is what the Dockerfile then sees.

Applying the plugin and running the first image build

The plugin is applied with the standard Gradle plugins convention, using its Maven coordinates under the `com.palantir.docker` id.

plugins {
    id 'com.palantir.docker' version '<version>'
}

A minimal configuration names the image and nothing else, which is enough for a Dockerfile that copies from the build context.

docker {
    name 'hub.docker.com/username/my-app:version'
}

The `docker` task builds the image and the `dockerPush` task pushes it to a Docker repository. The README notes that tag and push tasks are generated for each `tag` and `tags` entry, so a build with two configured tags exposes a separate push task per tag rather than one task that pushes everything. If your Dockerfile needs a distribution archive, the documented canonical form adds the task outputs to the context:

docker {
    name 'hub.docker.com/username/my-app:version'
    files tasks.distTar.outputs   // adds resulting *.tgz to the build context
}

Deprecated tags, build arguments and the cache flags

The configuration options have moved on over the years, and the shape of the block shows it. `tags` is explicitly marked deprecated and takes an argument list of tags to create, with any tag inside `name` stripped before a specific tag is applied; it defaults to the empty set. `tag` is the replacement, taking a task name and the tag to create. The parameter list also carries `buildArgs`, an argument map of string to string that becomes `--build-arg` parameters on the docker build command and defaults to empty, and `labels`, a string to string map that becomes `--label` parameters and defaults to no labels.

Two booleans control how the daemon behaves during the build. `pull` decides whether Docker tries to fetch a newer version of the base image before building, and it defaults to `false`. `noCache` adds the `--no-cache` option so the whole image is rebuilt from scratch, also defaulting to `false`. A project that wants reproducible builds therefore has to opt in to both, and a project that wants fast iteration accepts the risk of a stale base layer by default. The documentation also shows the fully populated form, where every option is set at once:

docker {
    name 'hub.docker.com/username/my-app:version'
    tags 'latest' // deprecated, use 'tag'
    tag 'myRegistry', 'my.registry.com/username/my-app:version'
    dockerfile file('Dockerfile')
    files tasks.distTar.outputs, 'file1.txt', 'file2.txt'
    buildArgs([BUILD_VERSION: 'version'])
    labels(['key': 'value'])
    pull true
    noCache true
}

Cross platform builds stay behind opt-in buildx flags

Multi platform output arrives as a separate group of options rather than as a change to the existing build path. `buildx` is a boolean that defines whether Docker build should use buildx for cross platform builds, and it defaults to `false`. `platform` is a list of strings that defines which platforms buildx should target, defaulting to empty. `builder` names the builder buildx should use and defaults to `null`. `load` adds the `--load` flag so the image lands in the local repository, and `push` adds the `--push` flag so it goes to a remote registry; both default to `false`.

The practical consequence is that a plain `docker` task and a buildx task are different code paths with different defaults, and the buildx ones are inert unless you switch them on. A cross platform build that forgets `load` leaves the image inside the builder rather than in the local Docker repository, and a build that sets `push` sends the artifact to a registry whether or not the surrounding CI expects that. Both flags are declared in the same `docker` block as everything else, so the switch between a local image and a published one is a one-line difference in the build script.

Image dependencies published as Maven coordinates

The `com.palantir.docker` and `com.palantir.docker-compose` plugins go further than building images. They let a project declare and resolve version aware dependencies between Docker images, with the stated use case of generating `docker-compose.yml` files whose image versions are mutually compatible when several images depend on the same Dockerized service. The `docker` plugin adds a `docker` Gradle component and a `docker` Gradle configuration for declaring and publishing dependencies on other containers.

Declaring the dependency and publishing it are two steps. The first uses the `maven-publish` plugin alongside the Docker plugin:

plugins {
    id 'maven-publish'
    id 'com.palantir.docker'
}

dependencies {
    docker 'foogroup:barmodule:0.1.2'
    docker project(":someSubProject")
}

The second turns that component into a publication, with the artifact id suffixed by `-docker`:

publishing {
    publications {
        dockerPublication(MavenPublication) {
            from components.docker
            artifactId project.name + "-docker"
        }
    }
}

This is the least ordinary part of the project. A Docker image becomes a resolvable dependency with a coordinate, so a downstream build can ask for a specific image version instead of pinning a tag by hand. It also means the plugin overlaps with Maven publishing, which is why the `maven-publish` plugin appears in the same block.

The end of life notice outranks the recent push

The repository carries an explicit disclaimer. It says the repo is end of life, that no new features will be accepted and no bugs will necessarily be fixed, that it is no longer used internally at Palantir, and that pull requests and issues for it are unmonitored. That statement comes from the project's own README, and it is the single most important fact for anyone considering the dependency.

The commit record does not contradict it in a simple way. The last push was on 2026-10-20, so the code moved recently, while the releases tell a slower story: version 0.40.0 was published on 2026-09-16, 0.39.0 also on 2026-09-16, and 0.38.0 on 2026-08-28. Two releases on one day and a maintenance push that postdates them suggest repository housekeeping rather than a stream of new features, though only the README states the intent. Nothing in the README describes a migration path, a replacement plugin, or a deprecation timeline for the three plugin ids.

The license is Apache-2.0, so the code can be read, modified and redistributed under that license. The default branch is `develop` and the implementation language is Groovy. Because the README declares that bug fixes are not guaranteed, anyone pinning this plugin should treat it as frozen code that happens to still be published to the Gradle plugin portal.

Where the compose and run plugins differ from a plain docker build

There are two different ways to use this project, and choosing between them is a design decision. The `com.palantir.docker` plugin alone wraps the docker build and push commands in Gradle tasks, which is the same shape as any shell script that calls `docker build` and `docker push`. What it adds is the wiring from Gradle outputs into the build context, and the ability to treat an image as a publishable dependency.

The `com.palantir.docker-compose` plugin takes a different approach. Instead of producing an image, it fills placeholders in a docker-compose template file with image versions resolved from those dependencies, so several services can be pinned to versions that agree with each other. The `com.palantir.docker-run` plugin is closer to a test harness: it starts, stops, status and cleans up a named container from a specified image, which is what a build would use to run the image it just produced.

If a build needs none of that dependency resolution, the plain Docker command line or a small script does the same job with fewer moving parts, and it will not break when a Groovy DSL changes. If a build does need images to be resolvable versions or wants a container lifecycle tied to Gradle tasks, that is where this plugin has a shape no shell script shares.

Editorial conclusion

Adopt gradle-docker only if your build already runs on Gradle and you want task outputs copied into the image automatically, and read the end of life notice first because no new features or guaranteed bug fixes are coming. Do not adopt it for a new service when your team needs a maintained plugin. Before anything else, check that the `docker` task pushes to a registry you control, that the `files` collection reaches your distribution archive, and that the last push on 2026-10-20 reflects the version of the plugin your build resolves.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. palantir/gradle-docker on GitHub
4. README
5. Releases