Java with Bitbucket Pipelines


This guide shows you how to use Bitbucket Pipelines for building and testing a Java software project in a Docker container, using either Maven or Gradle as your build tool.

If you'd prefer to quickly import a demo repository with a working pipeline to experiment with, have a look at our demo java repo.

Note: Bitbucket Pipelines includes fifty free minutes per account, at the time of writing. You can check your account's usage of minutes for the month by clicking Settings > Plan details in your workspace.

If you'd prefer to set it up by hand, most of the configuration happens in the bitbucket-pipelines.yml file that Pipelines uses to define the build.

Build and test Maven projects

Specify your Maven version with Docker

Bitbucket Pipelines runs all your builds in Docker containers using an image that you specify at the beginning of your configuration file. You can easily use Maven with Bitbucket Pipelines by using one of the official Maven Docker images on Docker Hub.

For instance, you can use Maven 3.3.9 (current version as of writing) by specifying it at the beginning of your bitbucket-pipelines.yml file.

1 2 3 4 5 6 image: maven:3.3.9 pipelines: default: - step: script: - mvn -version

You can check your bitbucket-pipelines.yml file with our online validator.

Java and JDK versions

By default, the Maven image will include a recent official version of the Java JDK, but you can specify a different version instead by using a specific Maven version. Below is an example using the Docker image for Maven 3.2.5 with JDK 1.7.

1 image: maven:3.2.5-jdk-7

You can find a list of available Maven/JDK versions and corresponding image tags, refer to

Build and run tests with Maven

Once you have selected your Docker image, running tests is just including the appropriate Maven commands in your Pipelines script. Here's an example.

1 2 3 4 5 6 image: maven:3.3.9 pipelines: default: - step: script: - mvn -B verify # -B batch mode makes Maven less verbose

Private Maven repositories

To access a private Maven repository, you'll need to override the default Maven settings.xml found in the Docker image at /usr/share/maven/conf/settings.xml.

Before using this example, configure two secure variables, MAVEN_USERNAME and MAVEN_PASSWORD, so we can pass these values securely to the Pipelines configuration.


1 2 3 4 5 6 7 8 9 image: maven:3.3.9 pipelines: branches: main: - step: script: - bash - mvn -B verify

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 #!/bin/bash sed -i~ "/<servers>/ a\ <server>\ <id>private-repo</id>\ <username>${MAVEN_USERNAME}</username>\ <password>${MAVEN_PASSWORD}</password>\ </server>" /usr/share/maven/conf/settings.xml sed -i "/<profiles>/ a\ <profile>\ <id>private-repo</id>\ <activation>\ <activeByDefault>true</activeByDefault>\ </activation>\ <repositories>\ <repository>\ <id>private-repo</id>\ <url></url>\ </repository>\ </repositories>\ <pluginRepositories>\ <pluginRepository>\ <id>private-repo</id>\ <url></url>\ </pluginRepository>\ </pluginRepositories>\ </profile>" /usr/share/maven/conf/settings.xml

Custom Maven settings.xml

Making more advanced changes to the default settings.xml with sed can be quite painful, so it may be easier to commit your own settings.xml to your Bitbucket repository. Then you can reference it using Maven's -s flag.

1 2 3 4 5 6 image: maven:3.3.9 pipelines: default: - step: script: - mvn -s settings.xml # e.g. with settings.xml in the root of the project

Build and test Gradle projects

Add the Gradle Wrapper to your repository

Our recommended approach (and Gradle's) to building Gradle projects is to commit the Gradle Wrapper to your repository.

The Gradle wrapper ensures two things:

  • the build environment doesn't need to have Gradle manually installed to build your project

  • your project is always built with the same Gradle version

We recommend making the wrapper script executable before committing it to your repository:

1 chmod +x gradlew

Then you can build your Gradle project with the wrapper:


1 2 3 4 5 6 image: openjdk:8 pipelines: default: - step: script: - bash ./gradlew build

Remember, you can check your bitbucket-pipelines.yml file with our online validator.

Last modified on Jun 9, 2021
Cached at 10:26 PM on Jun 11, 2021 |

Additional Help

Ask the Community