mirror of
https://github.com/gradle/gradle-build-action.git
synced 2024-10-06 03:36:48 +00:00
Update README for use without Gradle execution
This commit is contained in:
Daz DeBoer
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
|
||||
|
||||
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()
|
||||
|
|
|
|||
Loading…
Reference in a new issue