tianzixuan/gradle-build-action
1
0
Fork 0
mirror of https://github.com/gradle/gradle-build-action.git synced 2025-11-04 01:28:56 +08:00
Code Issues Packages Projects Releases Wiki Activity

Update README for use without Gradle execution

Browse Source
This commit is contained in:
Daz DeBoer
2021-12-08 13:33:39 -07:00
parent e977669c8c
commit 40c0a12211
1 changed files with 101 additions and 66 deletions
Download Patch File Download Diff File Expand all files Collapse all files

167
README.md
View File

@@ -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()