From b4e6c2b28aa4f4dde0bfc600b5d0822473675a22 Mon Sep 17 00:00:00 2001 From: Daz DeBoer Date: Fri, 17 Dec 2021 13:34:22 -0700 Subject: [PATCH] Minor improvements to README --- README.md | 42 +++++++++++++++++++++++++++--------------- 1 file changed, 27 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index 3c07afa7..16390332 100644 --- a/README.md +++ b/README.md @@ -4,11 +4,15 @@ This GitHub Action can be used to configure Gradle and optionally execute a Grad ## Usage -The following workflow will run `./gradlew build` on ubuntu, macos and windows. +The following workflows will execute a Gradle build on ubuntu, macos and windows. The only prerequisite is to have Java installed: you define the version of Java you need to run the build using the `actions/setup-java` action. +### Use the action to setup Gradle for later steps + +If you have an existing workflow invoking Gradle, you can simply add an initial "Setup Gradle" Step to benefit from caching, +build-scan capture and other features of the gradle-build-action. + ```yaml -# .github/workflows/gradle-build-pr.yml name: Run Gradle on PRs on: pull_request jobs: @@ -22,16 +26,20 @@ jobs: - uses: actions/setup-java@v1 with: java-version: 11 - - uses: gradle/gradle-build-action@v2 - with: - arguments: build + + - name: Setup Gradle + uses: gradle/gradle-build-action@v2 + + - name: Execute Gradle build + run: ./gradlew build ``` -The `gradle-build-action` can also be used for caching Gradle state without owning the actual Gradle execution. -The following workflow is effectively the same as the one above, but supports full scripting of the Gradle invocation. +### Use the action to setup and execute Gradle + +The `gradle-build-action` can also be used for the actual Gradle execution, by providing an `arguments` parameter. +The following workflow is effectively the same as the one above, without using a separate `run` step. ```yaml -# .github/workflows/gradle-build-pr.yml name: Run Gradle on PRs on: pull_request jobs: @@ -45,12 +53,17 @@ jobs: - uses: actions/setup-java@v1 with: java-version: 11 - - uses: gradle/gradle-build-action@v2 - - run: ./gradlew build + + - name: Setup and execute Gradle build + uses: gradle/gradle-build-action@v2 + with: + arguments: build ``` +### Multiple Gradle executions in the same Job + It is possible to configure multiple Gradle executions to run sequentially in the same job. -Each invocation will start its run with the filesystem state remaining from the previous execution. +The initial Action step will perform the Gradle setup. ```yaml - uses: gradle/gradle-build-action@v2 @@ -69,7 +82,7 @@ The same can be achieved with a single `gradle-build-action` step and multiple ` - run: ./gradlew check ``` -### Why is this better than running Gradle directly? +## Why use the `gradle-build-action`? It is possible to directly invoke Gradle in your workflow, and the `setup-java` action provides a simple way to cache Gradle dependencies. @@ -83,9 +96,9 @@ However, the `gradle-build-action` offers a number of advantages over this appro The `gradle-build-action` is designed to provide these benefits with minimal configuration. These features work both when Gradle is executed via the `gradle-build-action` and for any Gradle execution in subsequent steps. -## Gradle Installation +## Use specific Gradle version -The `gradle-build-action` will download and install a specified Gradle version, adding this installed version to the PATH. +The `gradle-build-action` will download, install and run a specified Gradle version, adding this installed version to the PATH. Downloaded Gradle versions are stored in the GitHub Actions cache, to avoid requiring downloading again later. ```yaml @@ -109,7 +122,6 @@ Moreover, you can use the following aliases: This can be handy to automatically verify your build works with the latest release candidate of Gradle: ```yaml -# .github/workflows/test-gradle-rc.yml name: Test latest Gradle RC on: schedule: