Building Gradle projects doesn’t stop with the developer’s machine. Continuous Integration (CI) has been a long-established practice for running a build for every single change committed to version control to tighten the feedback loop.

In this guide, we’ll discuss how to configure TeamCity for a typical Gradle project.

What you’ll need

  • About NN

  • A command prompt

  • The Java Development Kit (JDK), version 1.8 or higher

  • A TeamCity installation (setup steps explained in this guide)

Setup a typical project

For demonstration purposes, this guide is going to focus on building a Java-based project; however, this setup will work with any Gradle-compatible project. More specifically, a Gradle plugin written in Java and tested with Spock. First, we’ll get the project set up on your local machine before covering the same steps on CI.

Just follow these steps:

Clone the Gradle Site Plugin repository

git clone
cd gradle-site-plugin

Build the project

As a developer of a Java project, you’ll typical want to compile the source code, run the tests and assemble the JAR artifact. That’s no different for Gradle plugins. The following command achieves exactly that:

./gradlew build

14 actionable tasks: 14 executed

The project provides the Gradle Wrapper as part of the repository. It is a recommended practice for any Gradle project as it enables your project to built on CI without having to install the Gradle runtime.

Build scan integration

The sample project is equipped with support for generating build scans. Running the build with the command line option --scan renders a link in the console.

Publishing build scan...

Setup TeamCity

JetBrains TeamCity is a powerful and user-friendly Continuous Integration and Deployment server that works out of the box. JetBrains offers several licensing options that allow you to scale TeamCity to your needs. In this setup, we’ll use TeamCity Professional, a free fully functional edition suitable for average projects. In the course of this section, you’ll learn how to set up TeamCity, create a build configuration to pull the source code from GitHub and run the Gradle build.

Install and start TeamCity

On the TeamCity website you can pick from a variety of distributions. This post uses TeamCity bundled with Tomcat servlet container and covers the evaluation setup of a TeamCity server and a default build agent running on the same machine.

  1. Make sure you have JRE or JDK installed and the JAVA_HOME environment variable is pointing to the Java installation directory. Oracle Java 1.8 JDK is required.

  2. Download TeamCity .tar.gz distribution. Unpack the TeamCity<version number>.tar.gz archive, for example, using the WinZip, WinRar or a similar utility under Windows, or the following command under Linux or macOS:

tar xfz TeamCity<version number>.tar.gz
  1. Start the TeamCity server and one default agent at the same time, using the runAll script provided in the <TeamCity home>/bin directory, e.g. start
  1. To access the TeamCity Web UI, navigate to http://localhost:8111/. Follow the defaults of the TeamCity setup. You will be asked to set up a new administration user.

Next, we can set up the project and run a build in TeamCity.

Create a TeamCity build

Setting up a new Gradle build in TeamCity requires just a few clicks: TeamCity comes bundled with a Gradle plugin, so you do not need to install plugins additionally. However, it is recommended that you install the Gradle Build Scan plugin.

On the Administration | Projects page click Create project, use the option From the repository URL and enter the URL of the GitHub repository:

teamcity create project

Follow the Create Project wizard, it will prompt for the project and build configuration name and automatically detect build steps. Select the automatically Gradle build step and click Use selected:

teamcity build step

The build step is added to the build configuration:

teamcity step added

Click Edit, on the page that opens click Advanced options. Using the Wrapper to execute the build is considered good practice with Gradle, and on automatic detection this option is selected by default. We’ll want to generate a build scan, so we’ll enter the --scan option in Additional Gradle command line parameters field.

teamcity scan

Save the settings and we’re ready to run the build.

Run the build in TeamCity

Click the Run button in the right top corner:

teamcity step upd

TeamCity will start the build and you’ll be able to view the build progress by clicking Build Configuration Home. When the build is finished, you can review the build results by clicking the build number link:

teamcity results

You can view the tests right here in TeamCity:

teamcity tests

The information on parameters and environment of the build is available on the Parameters tab of the build results.

If you installed the Gradle Build Scan plugin, you will see a link to the build scan in the Build Results view:

teamcity build scan plugin

Otherwise, the link to the build scan for the given build is available in the build log:

teamcity log link

There are various options to trigger TeamCity builds continuously: from polling the repository periodically, to building on a set schedule, or via post-commit hook.

Further reading

You can learn more about advanced TeamCity usage through these resources:

More information is available in TeamCity documentation. Follow the TeamCity blog for the latest news.


Executing Gradle builds on CI can be set up and configured with just a handful of steps. The benefit of receiving fast feedback clearly speaks for itself. If you are not using TeamCity, no problem, many CI products tightly integrate with Gradle as a first-class citizen.

Help improve this guide

Have feedback or a question? Found a typo? Like all Gradle guides, help is just a GitHub issue away. Please add an issue or pull request to gradle-guides/executing-gradle-builds-on-teamcity and we’ll get back to you.