Skip to content
javahacks.dev
DevOps

How to Build and Push Docker Images in CI for Java

Build a Java application image in GitHub Actions and push it to a registry with Buildx, tags from Git, layer caching and a read-only token where possible.

6 min read
Summarize in AI
Flat illustration of shipping containers stacked on a ship, with the Docker, OpenJDK and Terraform logos.

Building a Docker image on your laptop and pushing it by hand works until the day it matters: the image was built from uncommitted code, nobody can say which commit is running, and the build only happens when one person is awake. The fix is to let CI build the image from a clean checkout, tag it with the commit it came from, and push it to a registry that your cluster pulls from. This post builds that pipeline in GitHub Actions for a Spring Boot service, with Buildx, meaningful tags, layer caching, multi-architecture output, a vulnerability scan and the rule for pull requests from forks. The examples use GitHub Container Registry, Docker Buildx 0.2x and JDK 25.

The workflow

Start with the image's recipe. A multi-stage Dockerfile keeps the build tools out of the final image, as shown in multi-stage Docker builds for Java:

DockerfileDockerfile
FROM eclipse-temurin:25-jdk AS build
WORKDIR /src
COPY mvnw pom.xml ./
COPY .mvn .mvn
RUN ./mvnw -B -ntp dependency:go-offline
COPY src src
RUN ./mvnw -B -ntp -DskipTests package

FROM eclipse-temurin:25-jre
WORKDIR /app
COPY --from=build /src/target/shop.jar app.jar
USER 10001
EXPOSE 8080
ENTRYPOINT ["java", "-jar", "app.jar"]

Then the workflow that builds and pushes it on every merge to main:

.github/workflows/image.ymlYAML
name: image

on:
  push:
    branches: [main]
    tags: ["v*"]

permissions:
  contents: read
  packages: write

jobs:
  image:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: docker/setup-buildx-action@v3

      - uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - id: meta
        uses: docker/metadata-action@v5
        with:
          images: ghcr.io/${{ github.repository }}
          tags: |
            type=sha
            type=ref,event=branch
            type=semver,pattern={{version}}

      - uses: docker/build-push-action@v6
        with:
          context: .
          push: true
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}
          cache-from: type=gha
          cache-to: type=gha,mode=max

Step by step: setup-buildx-action gives you the BuildKit builder. login-action authenticates to GitHub Container Registry using the workflow's own GITHUB_TOKEN, so no personal token is stored; the packages: write permission is what authorizes the push, and it is granted to this job only. metadata-action computes tags and OCI labels. build-push-action builds and pushes in one step. The steps follow the Docker CI documentation for GitHub Actions, and the registry side is described in the GitHub Container Registry guide.

After a run you can pull the result and check what you got:

Shell
docker pull ghcr.io/acme/shop:sha-3f9c1d2
docker image inspect ghcr.io/acme/shop:sha-3f9c1d2 --format '{{ index .Config.Labels "org.opencontainers.image.revision" }}'
Text
3f9c1d2e8a7b4c60d5e1f2a39b8c7d6e5f4a3b21

The label ties the image back to the exact commit, which is the answer to "what is running in production?".

Tags that mean something

The tag is how humans and deploy tools refer to an image, so pick tags that cannot lie.

TagMoves?Use
sha-3f9c1d2NeverDeploy this. It names one build of one commit
1.4.2Never, if you do not re-tagA release you chose to name
mainEvery mergeA convenience for staging, never for production
latestWhenever you sayAvoid; it hides what is running

Deploy by the immutable tag, or better by digest, so a rollback is a known image and not "whatever main was yesterday". A Kubernetes manifest pinned to sha-3f9c1d2 is reproducible; one pinned to latest is a surprise. If you re-push a mutable tag, nodes that already pulled it keep the old bytes unless imagePullPolicy: Always is set, which is how the same tag ends up running two different images.

Layer caching and the Dockerfile

CI runners start empty, so without a cache every build re-downloads every dependency. Two things make it fast, and they work together. The Dockerfile must order its layers from least to most changing: copy pom.xml, resolve dependencies, then copy src. A change to a source file then reuses the dependency layer. And the cache has to survive between runs, which cache-from: type=gha and cache-to: type=gha,mode=max do by storing BuildKit layers in the GitHub Actions cache. mode=max caches intermediate stages of a multi-stage build, not just the final one, which is what you want here since the expensive layer is in the build stage.

Measure the effect rather than trusting it. The build log marks reused layers:

Text
#9 [build 4/6] RUN ./mvnw -B -ntp dependency:go-offline
#9 CACHED

A line reading CACHED on the dependency layer means a source-only change skipped the download. The wider guidance on layering and base images is in writing a Java Dockerfile the right way. If the image builds but the container will not start, see a Spring Boot Docker image that does not start.

Multi-architecture images

Developers on Apple Silicon and servers on Graviton run arm64, while most CI and many clusters run amd64. A single tag can point to both through a manifest list. Add QEMU and ask for both platforms:

YAML
      - uses: docker/setup-qemu-action@v3
      - uses: docker/setup-buildx-action@v3
      - uses: docker/build-push-action@v6
        with:
          context: .
          platforms: linux/amd64,linux/arm64
          push: true
          tags: ${{ steps.meta.outputs.tags }}

The cost is time: emulated arm64 builds on an amd64 runner can be several times slower, especially for a Java build that runs a full test or compile in the container. Two remedies: compile the jar once outside Docker (a separate mvn package step) and have the Dockerfile only copy it, so the emulated part is a few COPY lines; or use a native arm64 runner for that platform. Only publish a platform you will actually run.

Scan and sign

An image is software, and it inherits the vulnerabilities of its base. Scan before you push anything to a place others deploy from. Trivy runs in one step:

YAML
      - uses: aquasecurity/[email protected]
        with:
          image-ref: ghcr.io/${{ github.repository }}:sha-${{ github.sha }}
          severity: CRITICAL,HIGH
          exit-code: "1"
          ignore-unfixed: true

ignore-unfixed avoids failing on issues with no available patch, which you cannot act on. Treat the scan as a signal, not a verdict: a vulnerability in a library the service never calls is real work to triage, and an automatic failure on every new CVE will teach the team to bypass the check. Signing with Sigstore's cosign adds proof of where an image came from, so a cluster policy can refuse unsigned images. Keep the base image current with a scheduled rebuild, since the JRE image receives security patches even when your code does not change.

Pushing from a pull request

Build the image on pull requests to catch Dockerfile breakage, but do not push it. A pull request from a fork has no access to your secrets or a write-scoped token, and you would not want to publish unreviewed code to your registry anyway. Set push conditionally:

YAML
      - uses: docker/build-push-action@v6
        with:
          context: .
          push: ${{ github.event_name != 'pull_request' }}
          tags: ${{ steps.meta.outputs.tags }}

A pull request then builds and discards, proving the image builds, and only merges to main publish. For the test build that runs before this one, see setting up Java CI with GitHub Actions. Give the image job needs: test so a red test run never produces a published image.

Where this does not apply

If you deploy to a platform that builds from source for you, such as a buildpack-based host, or you use spring-boot:build-image with Cloud Native Buildpacks, you do not need a Dockerfile, though the tagging and scanning advice carries over. If your registry is not GitHub's, change the login step and the image name, nothing else. And if you build rarely and by hand with a single deployment, a CI pipeline for the image is more machinery than you need yet; add it when a second person deploys.

Taggedhow to
Share

Keep reading

Get new posts by email

We send one email when a new post is published. No spam.

Unsubscribe in one click. No spam, ever.