CI/CD for Spring Boot with GitHub Actions

In 2022, a major fintech team I consulted for was deploying Spring Boot services manually via SSH. A developer fat-fingered a JAR filename at 11 PM on a Friday and took down payments processing for 40 minutes. The incident cost $200K in chargebacks and led to a three-week post-mortem. The fix was a proper CI/CD pipeline — something that should have existed from day one.

GitHub Actions has become the default CI/CD platform for Spring Boot projects because it lives where your code lives, requires zero infrastructure to bootstrap, and has a rich marketplace of pre-built actions. But most tutorials show only the happy path: compile, test, done. Production pipelines are far more nuanced.

A production-grade GitHub Actions pipeline for Spring Boot needs to handle dependency caching aggressively — cold Maven builds pull 500MB+ of artifacts. It needs matrix builds to catch JDK version drift. It needs Docker layer caching so a 3-minute image build doesn't become your pipeline bottleneck. It needs gated deployments so that staging gets every commit but production requires a manual approval.

SonarQube integration is non-negotiable for enterprise teams. Static analysis catches security vulnerabilities (SQL injection, XXE, SSRF) that unit tests will never find. Wiring sonar:analyze into your pipeline with quality gates that break the build on new critical findings is the difference between a security-conscious team and a breach waiting to happen.

This guide walks through a battle-tested GitHub Actions workflow for Spring Boot: from the first push that compiles your code all the way to a zero-downtime rolling deployment on AWS ECS or Kubernetes, with every production gotcha documented.

Multi-Stage Workflow Architecture

A production GitHub Actions workflow for Spring Boot should be structured as a directed acyclic graph of jobs, not a single monolithic job. Each job runs on its own fresh runner, which means you need to explicitly pass artifacts between jobs using actions/upload-artifact and actions/download-artifact. This isolation is a feature, not a bug — it ensures your test environment doesn't leak state into your build environment.

The canonical job order is: build-and-test → sonarqube (runs in parallel with test if you have a separate test report upload) → docker-build-push → deploy-staging → integration-test-staging → deploy-production. The deploy-production job should require a manual approval using GitHub's environment protection rules with required reviewers.

One critical mistake teams make is running all steps in a single job for simplicity. This means a Docker build failure wastes 5 minutes of test time on a re-run. Split jobs properly and use needs: to express dependencies. Use if: github.ref == 'refs/heads/main' to restrict deployment jobs to the main branch, preventing feature branch pushes from triggering deploys.

For monorepos containing multiple Spring Boot services, use path filters with dorny/paths-filter to only build and deploy services that have changed. Running a full pipeline for every service on every commit is a waste of runner minutes and slows down developer feedback loops significantly.

Maven and Gradle Dependency Caching

Dependency caching is the single highest-ROI optimization in Spring Boot pipelines. A cold Maven build for a medium Spring Boot application (50+ dependencies) downloads 300-600MB of artifacts. On a GitHub-hosted runner with ~100 Mbps bandwidth, that's 30-60 seconds of pure network I/O per run. Multiply that by 50 builds per day across a team and you're burning 25-50 minutes of developer wait time daily on artifact downloads alone.

The correct cache key strategy is a two-level key: a primary key that is an exact hash of all POM files, and a restore-keys fallback that matches any cache from the same OS. When dependencies don't change (most commits), you get 100% cache hits and spend ~2 seconds on cache restore instead of 60 seconds downloading. When you add a dependency, the primary key misses, the fallback key retrieves the old cache, Maven downloads only the new artifacts, and the cache saves the updated state for future runs.

For Gradle, use actions/setup-java with cache: gradle which handles the Gradle wrapper cache, build cache, and dependency cache automatically. For Maven, use cache: maven in setup-java or manage it manually with actions/cache if you need fine-grained control.

Docker layer caching is equally important. Use GitHub Actions Cache backend (cache-from: type=gha, cache-to: type=gha,mode=max) with docker/build-push-action. Combine this with a properly layered Dockerfile (dependencies layer first, application layer last) to achieve near-instant Docker builds when only application code changes.

Matrix Builds and SonarQube Integration

Matrix builds allow you to test your Spring Boot application against multiple JDK versions, operating systems, or database backends in parallel. This is essential for library authors and teams that need to support multiple JDK LTS versions (17, 21) or validate that their service works with both PostgreSQL 14 and 15.

The matrix strategy generates a Cartesian product of all specified dimensions. A matrix of jdk: [17, 21] and database: [postgres:14, postgres:15] produces 4 parallel jobs. Each job gets the matrix variables via ${{ matrix.jdk }} and ${{ matrix.database }}. Use fail-fast: false in production matrix configs so a failure in one combination doesn't cancel all other combinations — you want to see the full failure surface.

SonarQube integration requires careful setup. The most common mistake is not passing fetch-depth: 0 to actions/checkout, which truncates Git history and breaks SonarQube's blame data, leading to incorrect 'new code' calculations. SonarQube uses Git blame to determine which code is 'new' since the last analysis and applies different quality gate thresholds to new vs existing code.

For pull request analysis, SonarQube needs to know the base branch and PR number to decorate the PR with inline comments. Pass sonar.pullrequest.key, sonar.pullrequest.branch, and sonar.pullrequest.base from the GitHub Actions context. The GITHUB_TOKEN secret (automatically provided) needs to be passed as sonar.pullrequest.github.token for PR decoration to work.

Secrets Management and Security Hardening

GitHub Secrets is sufficient for most teams, but it has important limitations: secrets are flat key-value pairs with no hierarchy, no versioning, no rotation automation, and no audit log of which workflow used which secret. For regulated industries (finance, healthcare), you need a proper secrets management solution: AWS Secrets Manager, HashiCorp Vault, or Azure Key Vault.

The OIDC (OpenID Connect) approach for AWS authentication eliminates the need to store long-lived AWS credentials as GitHub Secrets entirely. Instead, GitHub Actions requests a short-lived OIDC token, exchanges it for AWS credentials via STS AssumeRoleWithWebIdentity, and the credentials expire after the job completes. This is the modern best practice — there are no static credentials to rotate, no risk of secret sprawl, and IAM policies can restrict which repos and branches can assume which roles.

For environment-specific secrets (dev/staging/prod), use GitHub Environments with environment-scoped secrets. The production environment should require manual approval and have protection rules preventing deployment from non-main branches. This means even if a developer pushes directly to main, they cannot bypass the approval gate for production deployment.

Security hardening for GitHub Actions workflows themselves: pin all third-party actions to SHA hashes, not tags. A malicious actor can push a new tag to a public action repo and inject code into your pipeline. uses: actions/checkout@v4 is vulnerable to a tag overwrite. uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 is immutable. Use step-security/harden-runner to restrict network egress from runner steps.

Deploy to AWS ECS and Kubernetes

Deploying to AWS ECS from GitHub Actions requires three steps: update the task definition JSON with the new image URI, register the new task definition revision, and update the ECS service to use it. AWS provides official actions for each step. The aws-actions/amazon-ecs-render-task-definition action substitutes the image URI into a task definition template stored in your repository, and aws-actions/amazon-ecs-deploy-task-definition registers and deploys it.

For Kubernetes deployments, the approach depends on your cluster access model. Direct kubectl access (using a kubeconfig stored as a GitHub Secret) is simple but grants broad cluster access to the pipeline. The better pattern is to use GitOps: the pipeline pushes a new image tag to a Helm values file or Kustomize overlay in a separate GitOps repository, and ArgoCD or Flux detects the change and deploys it. This separates CI (GitHub Actions) from CD (ArgoCD), gives you deployment history in Git, and allows rollback by reverting a commit.

For both ECS and Kubernetes, wait for the deployment to stabilize before marking the pipeline as successful. For ECS, use aws ecs wait services-stable. For Kubernetes, use kubectl rollout status deployment/my-app --timeout=5m. Failing to wait means your pipeline shows green while your application is still rolling out — or worse, while it's stuck in a crash loop.

Notifications, Observability, and Pipeline Hygiene

A CI/CD pipeline that silently fails is worse than no pipeline. Production teams need immediate, actionable notification when deployments fail. GitHub Actions natively supports Slack, PagerDuty, and email notifications via marketplace actions or simple webhook calls. The notification should include: which branch/PR caused the failure, which job failed, a link to the failed job logs, and the Git SHA for context.

Pipeline metrics matter as much as application metrics. Track pipeline duration trends over time — a build that was 3 minutes and is now 8 minutes signals accumulated technical debt (test suite growth, unoptimized Docker builds, cache misses). Use GitHub's built-in Actions usage reports or export metrics to Datadog/Grafana via the GitHub API.

Conditional notifications prevent alert fatigue. Only notify on failure (not success), and deduplicate — if three commits fail in quick succession on the same branch, send one notification, not three. For production deployments specifically, send a success notification to a deployment log channel so the team has a clear audit trail of what deployed when.

Pipeline hygiene: delete old workflow runs to keep the Actions tab navigable. Use concurrency: groups to cancel in-progress runs when a new commit is pushed to the same branch — there's no point finishing a build for a commit that's already been superseded. Set cancel-in-progress: true for feature branches but not for main, where you want every deploy to complete.

Containerize Your Spring Boot App Like a Pro (Buildpacks vs. Dockerfile)

You have two paths to package your Spring Boot 3.x app for CI/CD: a handwritten Dockerfile or Spring Boot's native Buildpacks support. Buildpacks win for most teams because they eliminate Dockerfile drift and security debt. They auto-detect your JDK version, layer your dependencies correctly, and produce OCI-compliant images without you touching a single FROM instruction. Your GitHub Action just needs the Paketo builder. The Buildpacks output is a lean image with optimized layer caching — your app code changes only invalidate the application layer, not the whole image. That shaves minutes off your deploy pipeline. Only drop to a custom Dockerfile when you need distroless images or exotic base layers like alpine-glibc. Even then, use multi-stage builds. Your production pipeline should never run 'docker build' with a single-stage file that copies your fat jar into a JDK image — that's a 400MB image for a 20MB app. That's amateur hour.

# io.thecodeforge — spring boot 3.x buildpacks action
name: Buildpacks CI
on:
  push:
    branches: [main]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-java@v4
        with:
          java-version: '21'
          distribution: 'temurin'
      - name: Build image with Paketo Buildpacks
        run: |
          ./mvnw spring-boot:build-image \
            -Dspring-boot.build-image.imageName=ghcr.io/${{ github.repository }}:latest
      - name: Push to registry
        run: |
          echo ${{ secrets.GITHUB_TOKEN }} | docker login ghcr.io -u ${{ github.actor }} --password-stdin
          docker push ghcr.io/${{ github.repository }}:latest

Docker Compose in CI? Nope. Use Testcontainers for Integration Tests

Don't run docker-compose up inside your GitHub Action. That's a recipe for flaky builds, port conflicts, and 3-minute container spin-up times. Spring Boot 3.x has Testcontainers integration built-in. Your CI pipeline should fire up a PostgreSQL container, your Redis cache, and your Kafka broker through @ServiceConnection annotations — directly in your test code. GitHub Actions runners have Docker sockets. Testcontainers uses them to create containers on-demand. Your pipeline stays clean: no docker-compose.yml in your repo, no environment-specific compose overrides, no 'docker-compose down' failure messing up your pipeline. Each test class gets its own container lifecycle. If a container crashes, the test fails fast with a clear error. The competitor pages show Docker Compose for local dev — fine. But for CI, Testcontainers is the only production-grade answer. Your pipeline should not care about port mappings or network names.

// io.thecodeforge — spring boot 3.x testcontainers
@SpringBootTest
@Testcontainers
class PaymentServiceIntegrationTest {

    @Container
    @ServiceConnection
    static PostgreSQLContainer<?> postgres = new PostgreSQLContainer<>("postgres:16-alpine");

    @Container
    @ServiceConnection
    static GenericContainer<?> redis = new GenericContainer<>(
            DockerImageName.parse("redis:7-alpine"))
            .withExposedPorts(6379);

    @Autowired
    private PaymentService paymentService;

    @Test
    void shouldProcessPaymentWithRealDatabaseAndCache() {
        Payment result = paymentService.process(new PaymentRequest(100.00, "USD"));
        assertThat(result.id()).isNotNull();
        // Container spins up in 4s, test runs, container dies.
    }
}