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.

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:
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:
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=maxStep 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:
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" }}'3f9c1d2e8a7b4c60d5e1f2a39b8c7d6e5f4a3b21The 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.
| Tag | Moves? | Use |
|---|---|---|
sha-3f9c1d2 | Never | Deploy this. It names one build of one commit |
1.4.2 | Never, if you do not re-tag | A release you chose to name |
main | Every merge | A convenience for staging, never for production |
latest | Whenever you say | Avoid; 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:
#9 [build 4/6] RUN ./mvnw -B -ntp dependency:go-offline
#9 CACHEDA 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:
- 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:
- uses: aquasecurity/[email protected]
with:
image-ref: ghcr.io/${{ github.repository }}:sha-${{ github.sha }}
severity: CRITICAL,HIGH
exit-code: "1"
ignore-unfixed: trueignore-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:
- 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.


