mirror of
https://github.com/gradle/gradle-build-action.git
synced 2024-12-27 01:02:11 -05:00
Update README for use without Gradle execution
This commit is contained in:
parent
e977669c8c
commit
40c0a12211
1 changed files with 101 additions and 66 deletions
167
README.md
167
README.md
|
@ -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()
|
||||||
|
|
Loading…
Reference in a new issue