Language Guide: Java

Tutorials & 2.0 Demo Apps > Language Guide: Java

This guide will help you get started with a Java application on CircleCI.


If you’re in a rush, just copy the sample configuration below into a .circleci/config.yml in your project’s root directory and start building.

We’re going to make a few assumptions here:

  • You are using Maven.
  • You are using Java 8.
  • You are using the Spring Framework. This project was generated using the Spring Initializer.
  • Your application can be distributed as an all-in-one uberjar.

Sample Configuration

version: 2 # use CircleCI 2.0
jobs: # a collection of steps
  build: # runs not using Workflows must have a `build` job as entry point
    working_directory: ~/circleci-demo-java-spring # directory where steps will run

    docker: # run the steps with Docker
      - image: circleci/openjdk:8-jdk-browsers # ...with this image as the primary container; this is where all `steps` will run

    steps: # a collection of executable commands

      - checkout # check out source code to working directory

      - restore_cache: # restore the saved cache after the first run or if `pom.xml` has changed
          key: circleci-demo-java-spring-{{ checksum "pom.xml" }}
      - run: mvn dependency:go-offline # gets the project dependencies
      - save_cache: # saves the project dependencies
            - ~/.m2
          key: circleci-demo-java-spring-{{ checksum "pom.xml" }}
      - run: mvn package # run the actual tests
      - store_test_results: # uploads the test metadata from the `target/surefire-reports` directory so that it can show up in the CircleCI dashboard. 
          path: target/surefire-reports
      - store_artifacts: # store the uberjar as an artifact
          path: target/demo-java-spring-0.0.1-SNAPSHOT.jar
      # See for deploy examples    

Get the Code

The configuration above is from a demo Java app, which you can access at

If you want to step through it yourself, you can fork the project on GitHub and download it to your machine. Go to the Add Projects page in CircleCI and click the Build Project button next to your project. Finally, delete everything in .circleci/config.yml.

Now we’re ready to build a config.yml from scratch.

Config Walkthrough

We always start with the version.

version: 2

Next, we have a jobs key. Each job represents a phase in your Build-Test-Deploy process. Our sample app only needs a build job, so everything else is going to live under that key.

In each job, we must specify a working_directory. In this sample config, we’ll name it after the project in our home directory.

version: 2
    working_directory: ~/circleci-demo-java-spring

This path will be used as the default working directory for the rest of the job unless otherwise specified.

Directly beneath working_directory, we can specify container images under a docker key.

version: 2
      - image: circleci/openjdk:8-jdk-browsers

We use the CircleCI OpenJDK Convenience images tagged to version 8-jdk-browsers which includes browsers for performing end-to-end testing.

Now we’ll add several steps within the build job.

We start with checkout so we can operate on the codebase.

Next we pull down the cache, if present. If this is your first run, or if you’ve changed pom.xml, this won’t do anything. We run mvn dependency:go-offline next to pull down the project’s dependencies. This allows us to insert a save_cache step that will store the dependencies in order to speed things up for next time.

Then mvn package runs the actual tests, and if they succeed, it creates an “uberjar” file containing the application source along with all its dependencies.

Next store_test_results uploads the test metadata from the target/surefire-reports directory so that it can show up in the CircleCI dashboard.

Finally we store the uberjar as an artifact using the store_artifacts step. From there this can be tied into a continuous deployment scheme of your choice.


      - checkout

      - restore_cache:
          key: circleci-demo-java-spring-{{ checksum "pom.xml" }}
      - run: mvn dependency:go-offline
      - save_cache:
            - ~/.m2
          key: circleci-demo-java-spring-{{ checksum "pom.xml" }}
      - run: mvn package
      - store_test_results:
          path: target/surefire-reports
      - store_artifacts:
          path: target/demo-java-spring-0.0.1-SNAPSHOT.jar

Nice! You just set up CircleCI for a Java app using Maven and Spring.


See the Deploy document for example deploy target configurations.