From 40c0a1221158db9c96ffb91f5a2bf03d62ddcbde Mon Sep 17 00:00:00 2001 From: Daz DeBoer Date: Wed, 8 Dec 2021 13:33:39 -0700 Subject: [PATCH] Update README for use without Gradle execution --- README.md | 167 +++++++++++++++++++++++++++++++++--------------------- 1 file changed, 101 insertions(+), 66 deletions(-) diff --git a/README.md b/README.md index 7c94dd4..3c07afa 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # Execute Gradle builds in GitHub Actions workflows -This GitHub Action can be used to execute a Gradle build on any platform supported by GitHub Actions. +This GitHub Action can be used to configure Gradle and optionally execute a Gradle build on any platform supported by GitHub Actions. ## Usage @@ -27,6 +27,28 @@ jobs: arguments: 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. + +```yaml +# .github/workflows/gradle-build-pr.yml +name: Run Gradle on PRs +on: pull_request +jobs: + gradle: + strategy: + matrix: + os: [ubuntu-latest, macos-latest, windows-latest] + runs-on: ${{ matrix.os }} + steps: + - uses: actions/checkout@v2 + - uses: actions/setup-java@v1 + with: + java-version: 11 + - uses: gradle/gradle-build-action@v2 + - run: ./gradlew build +``` + 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. @@ -39,6 +61,14 @@ Each invocation will start its run with the filesystem state remaining from the arguments: check ``` +The same can be achieved with a single `gradle-build-action` step and multiple `run` steps. + +```yaml +- uses: gradle/gradle-build-action@v2 +- run: ./gradlew assemble +- run: ./gradlew check +``` + ### Why is this better than running Gradle directly? It is possible to directly invoke Gradle in your workflow, and the `setup-java` action provides a simple way to cache Gradle dependencies. @@ -51,67 +81,12 @@ However, the `gradle-build-action` offers a number of advantages over this appro - [Automatic capture of build scan links](#build-scans) from the build, making these easier to locate for workflow run. 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 Execution +## Gradle Installation -### Command-line arguments - -The `arguments` input can used to pass arbitrary arguments to the `gradle` command line. -Arguments can be supplied in a single line, or as a multi-line input. - -Here are some valid examples: -```yaml -arguments: build -arguments: check --scan -arguments: some arbitrary tasks -arguments: build -PgradleProperty=foo -arguments: | - build - --scan - -PgradleProperty=foo - -DsystemProperty=bar -``` - -See `gradle --help` for more information. - -If you need to pass environment variables, use the GitHub Actions workflow syntax: - -```yaml -- uses: gradle/gradle-build-action@v2 - env: - CI: true - with: - arguments: build -``` - -### Gradle build located in a subdirectory - -By default, the action will execute Gradle in the root directory of your project. -Use the `build-root-directory` input to target a Gradle build in a subdirectory. - -```yaml -- uses: gradle/gradle-build-action@v2 - with: - build-root-directory: some/subdirectory -``` - -### Using a specific Gradle executable - -The action will first look for a Gradle wrapper script in the root directory of your project. -If not found, `gradle` will be executed from the PATH. -Use the `gradle-executable` input to execute using a specific Gradle installation. - -```yaml - - uses: gradle/gradle-build-action@v2 - with: - gradle-executable: /path/to/installed/gradle -``` - -This mechanism can also be used to target a Gradle wrapper script that is located in a non-default location. - -### Download, install and use a specific Gradle version - -The `gradle-build-action` is able to download and install a specific Gradle version to execute. +The `gradle-build-action` will download and install 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 - uses: gradle/gradle-build-action@v2 @@ -119,7 +94,7 @@ The `gradle-build-action` is able to download and install a specific Gradle vers gradle-version: 6.5 ``` -`gradle-version` can be set to any valid Gradle version. +The `gradle-version` parameter can be set to any valid Gradle version. Moreover, you can use the following aliases: @@ -150,9 +125,70 @@ jobs: - uses: gradle/gradle-build-action@v2 with: gradle-version: release-candidate - arguments: build --dry-run # just test build configuration + - run: gradle build --dry-run # just test build configuration ``` +## Gradle Execution + +If the action is configured with an `arguments` input, then Gradle will execute a Gradle build with the arguments provided. + +If no `arguments` are provided, the action will not execute Gradle, but will still cache Gradle state and configure build-scan capture for all subsequent Gradle executions. + +### Gradle command-line arguments + +The `arguments` input can used to pass arbitrary arguments to the `gradle` command line. +Arguments can be supplied in a single line, or as a multi-line input. + +Here are some valid examples: +```yaml +arguments: build +arguments: check --scan +arguments: some arbitrary tasks +arguments: build -PgradleProperty=foo +arguments: | + build + --scan + -PgradleProperty=foo + -DsystemProperty=bar +``` + +If you need to pass environment variables, use the GitHub Actions workflow syntax: + +```yaml +- uses: gradle/gradle-build-action@v2 + env: + CI: true + with: + arguments: build +``` + +### Gradle build located in a subdirectory + +By default, the action will execute Gradle in the root directory of your project. +Use the `build-root-directory` input to target a Gradle build in a subdirectory. + +```yaml +- uses: gradle/gradle-build-action@v2 + with: + arguments: build + build-root-directory: some/subdirectory +``` + +### Using a specific Gradle executable + +The action will first look for a Gradle wrapper script in the root directory of your project. +If not found, `gradle` will be executed from the PATH. +Use the `gradle-executable` input to execute using a specific Gradle installation. + +```yaml + - uses: gradle/gradle-build-action@v2 + with: + arguments: build + gradle-executable: /path/to/installed/gradle +``` + +This mechanism can also be used to target a Gradle wrapper script that is located in a non-default location. + ## Caching By default, this action aims to cache any and all reusable state that may be speed up a subsequent build invocation. @@ -257,7 +293,7 @@ and you can selectively [exclude content using `gradle-home-cache-exclude`](#gra If your build publishes a [build scan](https://gradle.com/build-scans/) the `gradle-build-action` action will: - Add a notice with the link to the GitHub Actions user interface -- Emit the link to the published build scan as an output named `build-scan-url`. +- For each step that executes Gradle, adds the link to the published build scan as a Step output named `build-scan-url`. You can then use that link in subsequent actions of your workflow. For example: @@ -274,9 +310,8 @@ jobs: with: java-version: 11 - uses: gradle/gradle-build-action@v2 - id: gradle - with: - arguments: build + - id: gradle + run: ./gradlew build - name: "Comment build scan url" uses: actions/github-script@v3 if: github.event_name == 'pull_request' && failure()