Update README for use without Gradle execution

This commit is contained in:
Daz DeBoer 2021-12-08 13:33:39 -07:00
parent e977669c8c
commit 40c0a12211
No known key found for this signature in database
GPG key ID: DD6B9F0B06683D5D

167
README.md
View file

@ -1,6 +1,6 @@
# Execute Gradle builds in GitHub Actions workflows # 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 ## Usage
@ -27,6 +27,28 @@ jobs:
arguments: build 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. 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. 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 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? ### 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. 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. - [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. 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 `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.
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.
```yaml ```yaml
- uses: gradle/gradle-build-action@v2 - 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: 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: Moreover, you can use the following aliases:
@ -150,9 +125,70 @@ jobs:
- uses: gradle/gradle-build-action@v2 - uses: gradle/gradle-build-action@v2
with: with:
gradle-version: release-candidate 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 ## Caching
By default, this action aims to cache any and all reusable state that may be speed up a subsequent build invocation. 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: 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 - 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: You can then use that link in subsequent actions of your workflow. For example:
@ -274,9 +310,8 @@ jobs:
with: with:
java-version: 11 java-version: 11
- uses: gradle/gradle-build-action@v2 - uses: gradle/gradle-build-action@v2
id: gradle - id: gradle
with: run: ./gradlew build
arguments: build
- name: "Comment build scan url" - name: "Comment build scan url"
uses: actions/github-script@v3 uses: actions/github-script@v3
if: github.event_name == 'pull_request' && failure() if: github.event_name == 'pull_request' && failure()