[[build_travis]]
= Executing Gradle builds on Travis CI

TIP: Top engineering teams using Travis CI have been able to reduce CI build time by up to 90% by using the Gradle Build Cache. https://gradle.com/training/build-cache-deep-dive/?bid=guides-execute-travisci[Register here] for our Build Cache training session to learn how your team can achieve similar results.

Building Gradle projects doesn't stop with the developer's machine.
https://en.wikipedia.org/wiki/Continuous_integration[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 link:https://travis-ci.org/[Travis CI] for a typical Gradle project.

== What you'll need

* A text editor
* A command prompt
* The Java Development Kit (JDK), version 1.8 or higher
* A https://gradle.org/install[Gradle distribution], version {gradle-version} or better

== Setup a typical project

As example, this guide is going to focus on a Java-based project.
More specifically, a Gradle plugin written in Java and tested with https://www.spekframework.org/[Spek].
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 https://github.com/gradle/gradle-site-plugin[Gradle Site Plugin] repository

[listing.terminal.sample-command]
----
$ git clone https://github.com/gradle/gradle-site-plugin.git
Cloning into 'gradle-site-plugin'...
$ 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:

[listing.terminal.sample-command]
----
$ ./gradlew build

BUILD SUCCESSFUL
14 actionable tasks: 14 executed
----

The project provides the link:{user-manual}gradle_wrapper.html[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 link:https://scans.gradle.com/[build scans].
Running the build with the command line option `--scan` renders a link in the console.

[listing.terminal.sample-command]
----
$ ./gradlew build --scan
Publishing build scan...
https://gradle.com/s/7mtynxxmesdio
----

The following section will describe how to build the project with the help of Travis CI.

== Configure Travis CI

Travis CI is a free, cloud-based CI solution provider making it an excellent choice for open source projects.
You can build any project as long as it is hosted on GitHub as public repository.
Travis CI doesn't not provide built-in options to post-process produced artifacts of the build e.g. host the JAR file or the HTML test reports.
You will have to use external services (like S3) to https://docs.travis-ci.com/user/uploading-artifacts/[transfer the files].

=== Create the configuration file

Travis CI requires you to check in a https://docs.travis-ci.com/user/customizing-the-build/[configuration file] with your source code named `.travis.yml`.
This file contains all relevant instructions for building the project.

The following configuration file tells Travis CI to build a Java project with JDK 8, skip the usual https://docs.travis-ci.com/user/customizing-the-build/#Skipping-the-Installation-Step[default execution step], and run the Gradle build with the Wrapper.

[listing]
----
language: java
install: skip

os: linux
dist: trusty
jdk: oraclejdk8

script:
  - ./gradlew build --scan -s
----

Select the project from the Travis CI profile.
After activating the repository from the dashboard, the project is ready to be built with every single commit.

image::ci-systems/travis-enable-project.png[Enabling a project]

NOTE: Configuring link:https://scans.gradle.com/[build scans] is especially helpful on cloud CI systems like Travis CI because it has additional environment and test results information that are difficult to obtain otherwise.

=== Enable caching of downloaded artifacts

Gradle's dependency management mechanism resolves declared modules and their corresponding artifacts from a binary repository.
Once downloaded, the files will be re-used from the cache.
You need to tell Travis CI explicitly that you want to https://docs.travis-ci.com/user/languages/java/#Caching[store and use the Gradle cache and Wrapper] for successive invocations of the build.

[listing]
----
before_cache:
  - rm -f  $HOME/.gradle/caches/modules-2/modules-2.lock
  - rm -fr $HOME/.gradle/caches/*/plugin-resolution/

cache:
  directories:
    - $HOME/.gradle/caches/
    - $HOME/.gradle/wrapper/
----

=== Further reading

You can learn more about advanced Travis CI usage through these resources:

* https://docs.travis-ci.com/user/encryption-keys/[Encrypting sensitive data]
* https://docs.travis-ci.com/user/build-stages/[Modelling a pipeline with build stages]

== Summary

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 Travis CI, no problem, many CI products tightly integrate with Gradle as a first-class citizen.
