diff --git a/docs/README.md b/docs/README.md index 220a5b9..cd5ce11 100644 --- a/docs/README.md +++ b/docs/README.md @@ -17,6 +17,7 @@ which is also used for tracking of community initiatives. ## Key sections +- [Gradle Cookbook](./cookbook/README.md) - [Participate and Contribute](./contributing/README.md) - Kernel parts, core plugins, and documentation - [Key Projects](./projects/README.md) - [Events and Mentorship programs](./events/README.md) diff --git a/docs/cookbook/README.md b/docs/cookbook/README.md new file mode 100644 index 0000000..a3f96a0 --- /dev/null +++ b/docs/cookbook/README.md @@ -0,0 +1,6 @@ +# The Gradle Cookbook + +This is a collection of guides and examples for the Gradle Build Tool. + +## Table of contents +* [Gradle Built Tool on CI](/community/cookbook/ci/jenkins/) \ No newline at end of file diff --git a/docs/cookbook/ci/github-actions.md b/docs/cookbook/ci/github-actions.md new file mode 100644 index 0000000..d5e8b8c --- /dev/null +++ b/docs/cookbook/ci/github-actions.md @@ -0,0 +1,197 @@ +# Executing Gradle builds on GitHub Actions + +**TIP:** Top engineering teams using GitHub Actions have been able to reduce CI build time by up to 90% by using the Gradle Build Cache. [Register here](https://gradle.org/training/#build-cache-deep-dive) 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. [Continuous Integration](https://en.wikipedia.org/wiki/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 [GitHub Actions](https://github.com/features/actions/) for a Gradle project hosted on GitHub. + +## Introduction + +GitHub Actions is a cloud-based CI solution provider built directly into GitHub, making it an excellent choice for projects hosted on GitHub. Using the [setup-gradle](https://github.com/gradle/actions/tree/main/setup-gradle) GitHub Action makes it simple to integrate any Gradle project into a GitHub Actions workflow. + +## What you'll need + +* A text editor +* A command prompt +* The Java Development Kit (JDK), version 1.8 or higher +* A local Gradle installation, to initialize a new Gradle project +* A GitHub account + +## Setup a Gradle project on GitHub + +If you have an existing Gradle project hosted on GitHub, then you can skip this step and move directly to [Configure GitHub Actions](#configure-github-actions). + +If not, follow these steps to initialize a new Gradle project on GitHub. + +### Create a new GitHub repository for your project + +Via the GitHub user interface, create a new repository named `github-actions-gradle-sample`. + +![Create new GitHub repository](images/github-actions-create-repository.png) + +### Clone the repository locally + +```shell +$ git clone git@github.com:/github-actions-gradle-sample.git +Cloning into 'github-actions-gradle-sample'... +$ cd github-actions-gradle-sample +``` + +### Initialize the Gradle project and commit to the repository + +Use `gradle init` to create a fresh Gradle project. You can choose any of the available options during `init`, but we recommend choosing "library" as the project type. + +Once the project is generated, commit the changes and push to the repository. + +```shell +$ gradle init +$ git add . +$ git commit -m "Initial commit" +$ git push +``` + +### Test building the project + +The project uses the [Gradle Wrapper](gradle_wrapper.adoc#gradle_wrapper_reference) for building the project. It is a recommended practice for any Gradle project as it enables your project to be built on CI without having to install the Gradle runtime. + +Before asking GitHub Actions to build your project, it's useful to ensure that it builds locally. Adding the "CI" environment variable will emulate running the build on GitHub Actions. + +The following command achieves that: + +```shell +$ CI=true ./gradlew build + +BUILD SUCCESSFUL +``` + +If the build works as expected, we are ready to build it with GitHub Actions. + +## Configure GitHub Actions + +You can create a GitHub Actions workflow by adding a `.github/workflows/.yml` file to your repository. This workflow definition file contains all relevant instructions for building the project on GitHub Actions. + +The following workflow file instructs GitHub Actions to build your Gradle project using the Gradle Wrapper, executed by the default Java distribution for GitHub Actions. Create a new file named `.github/workflows/build-gradle-project.yml` with the following content, and push it to the GitHub repository. + +```yaml +name: Build Gradle project + +on: + push: + +jobs: + build-gradle-project: + runs-on: ubuntu-latest + steps: + - name: Checkout project sources + uses: actions/checkout@v4 + + - name: Setup Gradle + uses: gradle/actions/setup-gradle@v3 + with: + build-scan-publish: true + build-scan-terms-of-use-url: "https://gradle.com/terms-of-service" + build-scan-terms-of-use-agree: "yes" + + - name: Run build + run: ./gradlew build +``` + +[Gradle Build Scans®](https://scans.gradle.com) are a great way to view your build results and provide valuable insights into your build. The workflow is configured to automatically publish a Build Scan for each build, accepting the legal terms of use. If you don't wish to publish Build Scans, you can remove this configuration from the workflow. + +Commit the changes and push to the repository: + +```shell +$ git add . +$ git commit -m "Add GitHub Actions workflow" +$ git push +``` + +## View the GitHub Actions results + +Once this workflow file is pushed, you should immediately see the workflow execution in the GitHub Actions page for your repository (e.g., https://github.com/gradle/gradle/actions). Any subsequent push to the repository will trigger the workflow to run. + +### List all runs of the GitHub Actions workflow + +The main actions page can be used to list all runs for a GitHub Actions workflow. + +![View workflow executions](images/github-actions-workflows.png) + +### See the results for GitHub Actions workflow run + +Clicking on the link for a workflow run will show the details of the workflow run, including a summary of all Gradle builds with links to any Build Scan published. + +**TIP:** Configuring [build scans](https://scans.gradle.com) is especially helpful on cloud CI systems like GitHub Actions because it has additional environment and test results information that are difficult to obtain otherwise. + +![View workflow execution details](images/github-actions-workflow.png) + +### View the details for Jobs and Steps in the workflow + +Finally, you can view the logs for the individual workflow Jobs and each Step defined for a Job: + +![View workflow job details](images/github-actions-job-details.png) + +## Enable caching of downloaded artifacts + +The [setup-gradle](https://github.com/gradle/actions/tree/main/setup-gradle) action used by this workflow will enable saving and restoring of the Gradle User Home directory in the built-in GitHub Actions cache. This will speed up your GitHub Actions build by avoiding the need to re-download Gradle versions and project dependencies, as well as re-using state from the previous workflow execution. + +Details about what entries are saved/restored from the cache can be viewed in the generated Job Summary: + +![View cache entry details](images/github-actions-cache-details.png) + +## Detect vulnerable dependencies with a dependency-submission workflow + +[GitHub supply chain security](https://docs.github.com/en/code-security/supply-chain-security/understanding-your-software-supply-chain/about-supply-chain-security) features will detect and alert about any dependencies that have known vulnerabilities. In order to do this, GitHub requires a complete dependency graph for your project. + +**NOTE:** Ensure that you have both [Dependency graph](https://docs.github.com/en/code-security/supply-chain-security/understanding-your-software-supply-chain/configuring-the-dependency-graph) and [Dependabot alerts](https://docs.github.com/en/code-security/dependabot/dependabot-alerts/configuring-dependabot-alerts#managing-dependabot-alerts-for-your-repository) enabled for your repository. + +The [dependency-submission](https://github.com/gradle/actions/tree/main/dependency-submission) action for Gradle provides the simplest way to generate a dependency graph for your project. This action will attempt to detect and upload a list of all dependencies used by your build. + +We recommend a separate GitHub Actions workflow for dependency submission. Create a GitHub Actions workflow by adding a `.github/workflows/.yml` file to your repository. Create a new file named `.github/workflows/gradle-dependency-submission.yml` with the following content, and push it to the GitHub repository. + +```yaml +name: Gradle Dependency Submission + +on: + push: + branches: + - main + +jobs: + dependency-submission: + runs-on: ubuntu-latest + steps: + - name: Checkout project sources + uses: actions/checkout@v4 + + - name: Generate and submit dependency graph + uses: gradle/actions/dependency-submission@v3 + with: + build-scan-publish: true + build-scan-terms-of-use-url: "https://gradle.com/terms-of-service" + build-scan-terms-of-use-agree: "yes" +``` + +[Gradle Build Scans®](https://scans.gradle.com) are a great way to view your build results and provide valuable insights into your build. The workflow is configured to automatically publish a Build Scan for each build, accepting the legal terms of use. If you don't wish to publish Build Scans, you can remove this configuration from the workflow. + +Commit the changes and push to the repository: + +```shell +$ git add . +$ git commit -m "Add Dependency submission workflow" +$ git push +``` + +### Viewing the dependency graph + +Once the dependency-submission workflow has completed, you can view all reported dependencies by navigating to `Insights -> Dependency graph`. + +This image reveals that the repository contains a version of `com.google.guava:guava` with a moderate vulnerability. + +![View dependency graph](images/github-actions-dependency-graph.png) + +### Viewing all dependency alerts + +You can view a list of all vulnerabilities by navigating to `Security -> Dependabot`. + +![View dependency alerts](images/github-actions-dependency-alerts.png) \ No newline at end of file diff --git a/docs/cookbook/ci/images/github-actions-cache-details.png b/docs/cookbook/ci/images/github-actions-cache-details.png new file mode 100644 index 0000000..537f71c Binary files /dev/null and b/docs/cookbook/ci/images/github-actions-cache-details.png differ diff --git a/docs/cookbook/ci/images/github-actions-create-repository.png b/docs/cookbook/ci/images/github-actions-create-repository.png new file mode 100644 index 0000000..c6c24e6 Binary files /dev/null and b/docs/cookbook/ci/images/github-actions-create-repository.png differ diff --git a/docs/cookbook/ci/images/github-actions-dependency-alerts.png b/docs/cookbook/ci/images/github-actions-dependency-alerts.png new file mode 100644 index 0000000..5fc435e Binary files /dev/null and b/docs/cookbook/ci/images/github-actions-dependency-alerts.png differ diff --git a/docs/cookbook/ci/images/github-actions-dependency-graph.png b/docs/cookbook/ci/images/github-actions-dependency-graph.png new file mode 100644 index 0000000..dd69bc9 Binary files /dev/null and b/docs/cookbook/ci/images/github-actions-dependency-graph.png differ diff --git a/docs/cookbook/ci/images/github-actions-job-details.png b/docs/cookbook/ci/images/github-actions-job-details.png new file mode 100644 index 0000000..c14e21d Binary files /dev/null and b/docs/cookbook/ci/images/github-actions-job-details.png differ diff --git a/docs/cookbook/ci/images/github-actions-workflow.png b/docs/cookbook/ci/images/github-actions-workflow.png new file mode 100644 index 0000000..f45ed92 Binary files /dev/null and b/docs/cookbook/ci/images/github-actions-workflow.png differ diff --git a/docs/cookbook/ci/images/github-actions-workflows.png b/docs/cookbook/ci/images/github-actions-workflows.png new file mode 100644 index 0000000..b92bed8 Binary files /dev/null and b/docs/cookbook/ci/images/github-actions-workflows.png differ diff --git a/docs/cookbook/ci/images/jenkins-build-scan.png b/docs/cookbook/ci/images/jenkins-build-scan.png new file mode 100644 index 0000000..d548b6c Binary files /dev/null and b/docs/cookbook/ci/images/jenkins-build-scan.png differ diff --git a/docs/cookbook/ci/images/jenkins-build-step.png b/docs/cookbook/ci/images/jenkins-build-step.png new file mode 100644 index 0000000..4efc09b Binary files /dev/null and b/docs/cookbook/ci/images/jenkins-build-step.png differ diff --git a/docs/cookbook/ci/images/jenkins-scm.png b/docs/cookbook/ci/images/jenkins-scm.png new file mode 100644 index 0000000..16d15c4 Binary files /dev/null and b/docs/cookbook/ci/images/jenkins-scm.png differ diff --git a/docs/cookbook/ci/images/teamcity-build-scan-plugin.png b/docs/cookbook/ci/images/teamcity-build-scan-plugin.png new file mode 100644 index 0000000..516d9df Binary files /dev/null and b/docs/cookbook/ci/images/teamcity-build-scan-plugin.png differ diff --git a/docs/cookbook/ci/images/teamcity-build-step.png b/docs/cookbook/ci/images/teamcity-build-step.png new file mode 100644 index 0000000..e8fd0e1 Binary files /dev/null and b/docs/cookbook/ci/images/teamcity-build-step.png differ diff --git a/docs/cookbook/ci/images/teamcity-create-project.png b/docs/cookbook/ci/images/teamcity-create-project.png new file mode 100644 index 0000000..fb89cac Binary files /dev/null and b/docs/cookbook/ci/images/teamcity-create-project.png differ diff --git a/docs/cookbook/ci/images/teamcity-log-link.png b/docs/cookbook/ci/images/teamcity-log-link.png new file mode 100644 index 0000000..9083974 Binary files /dev/null and b/docs/cookbook/ci/images/teamcity-log-link.png differ diff --git a/docs/cookbook/ci/images/teamcity-results.png b/docs/cookbook/ci/images/teamcity-results.png new file mode 100644 index 0000000..68608a8 Binary files /dev/null and b/docs/cookbook/ci/images/teamcity-results.png differ diff --git a/docs/cookbook/ci/images/teamcity-scan.png b/docs/cookbook/ci/images/teamcity-scan.png new file mode 100644 index 0000000..bc4e49f Binary files /dev/null and b/docs/cookbook/ci/images/teamcity-scan.png differ diff --git a/docs/cookbook/ci/images/teamcity-step-added.png b/docs/cookbook/ci/images/teamcity-step-added.png new file mode 100644 index 0000000..763ba78 Binary files /dev/null and b/docs/cookbook/ci/images/teamcity-step-added.png differ diff --git a/docs/cookbook/ci/images/teamcity-step-upd.png b/docs/cookbook/ci/images/teamcity-step-upd.png new file mode 100644 index 0000000..7c31be7 Binary files /dev/null and b/docs/cookbook/ci/images/teamcity-step-upd.png differ diff --git a/docs/cookbook/ci/images/teamcity-tests.png b/docs/cookbook/ci/images/teamcity-tests.png new file mode 100644 index 0000000..a975d53 Binary files /dev/null and b/docs/cookbook/ci/images/teamcity-tests.png differ diff --git a/docs/cookbook/ci/images/travis-enable-project.png b/docs/cookbook/ci/images/travis-enable-project.png new file mode 100644 index 0000000..36e1610 Binary files /dev/null and b/docs/cookbook/ci/images/travis-enable-project.png differ diff --git a/docs/cookbook/ci/jenkins.md b/docs/cookbook/ci/jenkins.md new file mode 100644 index 0000000..f111402 --- /dev/null +++ b/docs/cookbook/ci/jenkins.md @@ -0,0 +1,110 @@ +# Executing Gradle builds on Jenkins + +**TIP:** Top engineering teams using Jenkins have been able to reduce CI build time by up to 90% by using the Gradle Build Cache. [Register here](https://gradle.org/training/#build-cache-deep-dive) 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. [Continuous Integration](https://en.wikipedia.org/wiki/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 [Jenkins](https://jenkins.io/) for a typical Gradle project. + +## What you'll need + +- A text editor +- A command prompt +- The Java Development Kit (JDK), version 1.7 or higher +- A Jenkins installation (setup steps explained in this post) + +## Setup a typical project + +As an example, this guide is going to focus on a Java-based project. More specifically, a Gradle plugin written in Java and tested with [Spek](https://www.spekframework.org/). 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](https://github.com/gradle/gradle-site-plugin) repository + +```bash +$ 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 typically 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: + +```bash +$ ./gradlew build + +BUILD SUCCESSFUL +14 actionable tasks: 14 executed +``` + +The project provides the [Gradle Wrapper](gradle_wrapper.adoc#gradle_wrapper_reference) as part of the repository. It is a recommended practice for any Gradle project as it enables your project to be built on CI without having to install the Gradle runtime. + +### Build scan integration + +The sample project is equipped with support for generating [build scans](https://scans.gradle.com/). Running the build with the command line option `--scan` renders a link in the console. + +```bash +$ ./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 Jenkins. + +## Setup Jenkins + +Jenkins is one of the most prominent players in the field. In the course of this section, you'll learn how to set up Jenkins, configure a job to pull the source code from GitHub, and run the Gradle build. + +### Install and start Jenkins + +On the [Jenkins website](https://jenkins.io/download/), you can pick from a variety of distributions. This post uses the runnable WAR file. A simple Java command brings up the Jenkins server. + +```bash +$ wget https://mirrors.jenkins.io/war-stable/latest/jenkins.war +$ java -jar jenkins.war +``` + +In the browser, navigate to `localhost` with port `8080` to render the Jenkins dashboard. You will be asked to set up a new administration user and which plugins to install. + +### Installation of plugins + +Confirm to install the recommended plugins when starting Jenkins for the first time. Under "Manage Jenkins > Manage Plugins," ensure that you have the following two plugins installed: + +- [Git plugin](https://plugins.jenkins.io/git) +- [Gradle plugin](https://plugins.jenkins.io/gradle) + +Next, we can set up the job for building the project. + +## Create a Jenkins job + +Setting up a new Gradle job can be achieved with just a couple of clicks. From the left navigation bar, select "New Item > Freestyle project". Enter a new name for the project. We'll pick "gradle-site-plugin" for the project. + +Select the radio button "Git" in the section "Source Code Management". Enter the URL of the GitHub repository: `https://github.com/gradle/gradle-site-plugin.git`. + +![Source Code Management](images/jenkins-scm.png) + +Furthermore, create a "Build step" in the section "Build" by selecting "Invoke Gradle script". As mentioned before, we'll want to use the Wrapper to execute the build. In the "Tasks" input box, enter `build` and use the "Switches" `--scan -s` to generate a build scan and render a stack trace in case of a build failure. + +![Build Step](images/jenkins-build-step.png) + +### Execute the job + +Save the configuration of the job and execute an initial build by triggering the "Build Now" button. The build should finish successfully and render a "Gradle Build Scan" icon that brings you directly to the [build scan](https://scans.gradle.com) for the given build. + +![Build Scan](images/jenkins-build-scan.png) + +There are various options to trigger Jenkins builds continuously: from polling the repository periodically, to building on a set schedule, or via callback URL. + +## Further reading + +You can learn more about advanced Jenkins usage through these resources: + +- [Using credentials with Jenkins](https://jenkins.io/doc/book/using/using-credentials/) +- [Pipeline as code with Jenkins](https://jenkins.io/solutions/pipeline/) +- [Modeling a Continuous Deployment pipeline for a Spring Boot application](https://bmuschko.com/blog/jenkins-build-pipeline/) + +## 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 Jenkins, no problem, many CI products tightly integrate with Gradle as a first-class citizen. \ No newline at end of file diff --git a/docs/cookbook/ci/teamcity.md b/docs/cookbook/ci/teamcity.md new file mode 100644 index 0000000..7cc4946 --- /dev/null +++ b/docs/cookbook/ci/teamcity.md @@ -0,0 +1,136 @@ +# Executing Gradle builds on TeamCity + +**TIP:** Top engineering teams using TeamCity have been able to reduce CI build time by up to 90% by using the Gradle Build Cache. [Register here](https://gradle.org/training/#build-cache-deep-dive) 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. [Continuous Integration](https://en.wikipedia.org/wiki/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](https://www.jetbrains.com/teamcity/) for a typical Gradle project. + +## What you'll need + +- 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 [Spek](https://www.spekframework.org/). 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](https://github.com/gradle/gradle-site-plugin) repository + +```bash +$ 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 typically 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: + +```bash +$ ./gradlew build + +BUILD SUCCESSFUL +14 actionable tasks: 14 executed +``` + +The project provides the [Gradle Wrapper](gradle_wrapper.adoc#gradle_wrapper_reference) as part of the repository. It is a recommended practice for any Gradle project as it enables your project to be built on CI without having to install the Gradle runtime. + +### Build scan integration + +The sample project is equipped with support for generating [build scans](https://scans.gradle.com/). Running the build with the command line option `--scan` renders a link in the console. + +```bash +$ ./gradlew build --scan +Publishing build scan... +https://gradle.com/s/7mtynxxmesdio +``` + +## 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](https://www.jetbrains.com/teamcity/download/), 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.tar.gz` archive, for example, using the WinZip, WinRar or a similar utility under Windows, or the following command under Linux or macOS: + + ```bash + tar xfz TeamCity.tar.gz + ``` + +3. Start the TeamCity server and one default agent at the same time, using the runAll script provided in the `/bin` directory, e.g. + + ```bash + runAll.sh start + ``` + +4. 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 [TeamCity Build Scan plugin](https://plugins.jetbrains.com/plugin/9326-gradle-build-scan-integration). + +On the **Administration | Projects** page click _Create project_, use the option _From the repository URL_ and enter the URL of the GitHub repository: `https://github.com/gradle/gradle-site-plugin.git`. + +![Source Code Management](images/teamcity-create-project.png) + +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_: + +![Build Step](images/teamcity-build-step.png) + +The build step is added to the build configuration: + +![Step Added](images/teamcity-step-added.png) + +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. + +![Scan Option](images/teamcity-scan.png) + +Save the settings and we’re ready to run the build. + +### Run the build in TeamCity + +Click the _Run_ button in the top right corner: + +![Run Build](images/teamcity-step-upd.png) + +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: + +![Build Results](images/teamcity-results.png) + +You can view the tests right here in TeamCity: + +![Tests](images/teamcity-tests.png) + +The information on parameters and environment of the build is available on the _Parameters_ tab of the build results. + +If you installed the [TeamCity Build Scan plugin](https://plugins.jetbrains.com/plugin/9326-gradle-build-scan-integration), you will see a link to the build scan in the Build Results view: + +![Build Scan Plugin](images/teamcity-build-scan-plugin.png) + +Otherwise, the link to the [build scan](https://scans.gradle.com) for the given build is available in the build log: + +![Build Log Link](images/teamcity-log-link.png) + +There are various options to trigger TeamCity builds continuously: from [polling the repository](https://www.jetbrains.com/help/teamcity/configuring-build-triggers.html) periodically, to [building on a set schedule](https://www.jetbrains.com/help/teamcity/configuring-schedule-triggers.html), or via [post-commit hook](https://www.jetbrains.com/help/teamcity/configuring-vcs-post-commit-hooks-for-teamcity.html). + +## Further reading + +You can learn more about advanced TeamCity usage through these resources: + +- [Build chains and dependencies](https://www.jetbrains.com/help/teamcity/build-dependencies-setup.html) +- [Remote run and pre-tested commit](https://www.jetbrains.com/help/teamcity/pre-tested-delayed-commit.html) + +More information is available in [TeamCity documentation](https://www.jetbrains.com/help/teamcity/teamcity-documentation.html). Follow the [TeamCity blog](https://blog.jetbrains.com/teamcity/) for the latest news. + +## 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 TeamCity, no problem, many CI products tightly integrate with Gradle as a first-class citizen. \ No newline at end of file diff --git a/docs/cookbook/ci/travis-ci.md b/docs/cookbook/ci/travis-ci.md new file mode 100644 index 0000000..a433f5a --- /dev/null +++ b/docs/cookbook/ci/travis-ci.md @@ -0,0 +1,106 @@ +# 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. [Register here](https://gradle.org/training/#build-cache-deep-dive) 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. [Continuous Integration](https://en.wikipedia.org/wiki/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 [Travis CI](https://travis-ci.org/) 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 + +## 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 [Spek](https://www.spekframework.org/). 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](https://github.com/gradle/gradle-site-plugin) repository + +```shell +$ 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 typically 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: + +```shell +$ ./gradlew build + +BUILD SUCCESSFUL +14 actionable tasks: 14 executed +``` + +The project provides the [Gradle Wrapper](gradle_wrapper.adoc#gradle_wrapper_reference) as part of the repository. It is a recommended practice for any Gradle project as it enables your project to be built on CI without having to install the Gradle runtime. + +### Build scan integration + +The sample project is equipped with support for generating [build scans](https://scans.gradle.com/). Running the build with the command line option `--scan` renders a link in the console. + +```shell +$ ./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 a public repository. Travis CI does 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 [transfer the files](https://docs.travis-ci.com/user/uploading-artifacts/). + +### Create the configuration file + +Travis CI requires you to check in a [configuration file](https://docs.travis-ci.com/user/customizing-the-build/) 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 [default execution step](https://docs.travis-ci.com/user/customizing-the-build/#Skipping-the-Installation-Step), and run the Gradle build with the Wrapper. + +```yaml +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. + +![Enabling a project](images/travis-enable-project.png) + +**NOTE:** Configuring [build scans](https://scans.gradle.com/) 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 [store and use the Gradle cache and Wrapper](https://docs.travis-ci.com/user/languages/java/#Caching) for successive invocations of the build. + +```yaml +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: + +* [Encrypting sensitive data](https://docs.travis-ci.com/user/encryption-keys/) +* [Modelling a pipeline with build stages](https://docs.travis-ci.com/user/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. \ No newline at end of file diff --git a/mkdocs-dotorg.yml b/mkdocs-dotorg.yml index 06ab30b..f2695ca 100644 --- a/mkdocs-dotorg.yml +++ b/mkdocs-dotorg.yml @@ -104,14 +104,22 @@ extra: nav: - Home: README.md + - Cookbook: + - Gradle on CI: + - Jenkins: cookbook/ci/jenkins.md + - TeamCity: cookbook/ci/teamcity.md + - Github Actions: cookbook/ci/github-actions.md + - Travis CI: cookbook/ci/travis-ci.md - Participate: - Getting Started: contributing/README.md - Community Slack: contributing/community-slack.md - - Contribute to Gradle Build Tool: gradle/CONTRIBUTING.md + - Contributing to Gradle Build Tool: + - Overview: gradle/CONTRIBUTING.md + - Gradle Build Tool Architecture: gradle/architecture/README.md - Contributing to Documentation: - Overview: contributing/documentation/README.md - Gradle Build Tool Docs: gradle/platforms/documentation/docs/README.md - - Community Site docs: CONTRIBUTING.md + - Community Site Docs: CONTRIBUTING.md - Reporting Vulnerabilities: dotgithub/SECURITY.md - Public Roadmap: roadmap/README.md - Code of Conduct: dotgithub/CODE_OF_CONDUCT.md @@ -162,12 +170,12 @@ plugins: - multirepo: cleanup: false keep_docs_dir: true - nav_repos: + nav_repos: - name: dotgithub import_url: 'https://github.com/gradle/.github?branch=master&edit_uri=/blob/master/' - name: gradle import_url: 'https://github.com/gradle/gradle?branch=master&edit_uri=/blob/master/' - imports: [ "/*.md", "/*.png", "platforms/documentation/docs/README.md" ] + imports: [ "/*.md", "/*.png", "platforms/documentation/docs/README.md", "architecture/*", "architecture/standards/*" ] - name: roadmap import_url: 'https://github.com/gradle/build-tool-roadmap?branch=main&edit_uri=/blob/main/' imports: [ "README.md" ] diff --git a/mkdocs.yml b/mkdocs.yml index c306727..9074762 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -104,15 +104,23 @@ extra: nav: - Home: README.md + - Cookbook: + - Gradle on CI: + - Jenkins: cookbook/ci/jenkins.md + - TeamCity: cookbook/ci/teamcity.md + - Github Actions: cookbook/ci/github-actions.md + - Travis CI: cookbook/ci/travis-ci.md - Participate: - Getting Started: contributing/README.md - Community Slack: contributing/community-slack.md - Spread the Word: contributing/spread-the-word.md - - Contribute to Gradle Build Tool: gradle/CONTRIBUTING.md + - Contributing to Gradle Build Tool: + - Overview: gradle/CONTRIBUTING.md + - Gradle Build Tool Architecture: gradle/architecture/README.md - Contributing to Documentation: - Overview: contributing/documentation/README.md - Gradle Build Tool Docs: gradle/platforms/documentation/docs/README.md - - Community Site docs: CONTRIBUTING.md + - Community Site Docs: CONTRIBUTING.md - Reporting Vulnerabilities: dotgithub/SECURITY.md - Public Roadmap: roadmap/README.md - Code of Conduct: dotgithub/CODE_OF_CONDUCT.md @@ -168,7 +176,7 @@ plugins: import_url: 'https://github.com/gradle/.github?branch=master&edit_uri=/blob/master/' - name: gradle import_url: 'https://github.com/gradle/gradle?branch=master&edit_uri=/blob/master/' - imports: [ "/*.md", "/*.png", "platforms/documentation/docs/README.md" ] + imports: [ "/*.md", "/*.png", "platforms/documentation/docs/README.md", "architecture/*", "architecture/standards/*" ] - name: roadmap import_url: 'https://github.com/gradle/build-tool-roadmap?branch=main&edit_uri=/blob/main/' imports: [ "README.md" ]