gradle/actions
1
0
Fork 0
mirror of https://github.com/gradle/actions synced 2024-11-27 11:52:24 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 1

Update README for v2

Browse source
This commit is contained in:
Daz DeBoer 2021-09-28 11:30:55 -06:00 committed by GitHub
parent 83e2129213
commit 21dee71590
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 79 additions and 55 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

134
README.md
View file

@ -2,9 +2,13 @@
This GitHub Action can be used to execute a Gradle build on any platform supported by GitHub Actions.
**Note:** The following documentation is for `gradle/gradle-build-action@v2`, currently in Beta release.
You can view the documentation for the latest stable release (v1.5.1) [on the GitHub Marketplace](https://github.com/marketplace/actions/gradle-build-action?version=v1.5.1).
## Usage
The following workflow will run `./gradlew build` using the wrapper from the repository on ubuntu, macos and windows. The only prerequisite is to have Java installed: you define the version of Java you need to run the build using the `actions/setup-java` action.
The following workflow will run `./gradlew build` on ubuntu, macos and windows.
The only prerequisite is to have Java installed: you define the version of Java you need to run the build using the `actions/setup-java` action.
```yaml
# .github/workflows/gradle-build-pr.yml
@ -21,12 +25,26 @@ jobs:
- uses: actions/setup-java@v1
with:
java-version: 11
- uses: gradle/gradle-build-action@v1
- uses: gradle/gradle-build-action@v2
with:
arguments: build
```
## Gradle arguments
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.
```yaml
- uses: gradle/gradle-build-action@v2
with:
arguments: assemble
- uses: gradle/gradle-build-action@v2
with:
arguments: check
```
## Gradle Execution
### Command-line arguments
The `arguments` input can used to pass arbitrary arguments to the `gradle` command line.
@ -42,42 +60,47 @@ arguments: build -DsystemProperty=bar
See `gradle --help` for more information.
If you need to pass environment variables, simply use the GitHub Actions workflow syntax:
If you need to pass environment variables, use the GitHub Actions workflow syntax:
```yaml
- uses: gradle/gradle-build-action@v1
- uses: gradle/gradle-build-action@v2
env:
CI: true
with:
arguments: build
```
## Run a build from a different directory
### 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@v1
- uses: gradle/gradle-build-action@v2
with:
build-root-directory: some/subdirectory
```
## Use a specific `gradle` executable
### 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@v1
- uses: gradle/gradle-build-action@v2
with:
gradle-executable: path/to/gradle
gradle-executable: /path/to/installed/gradle
```
## Use a Gradle wrapper from a different directory
```yaml
- uses: gradle/gradle-build-action@v1
with:
gradle-executable: path/to/gradlew
```
This mechanism can also be used to target a Gradle wrapper script that is located in a non-default location.
## Setup and use a declared Gradle version
### 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
- uses: gradle/gradle-build-action@v1
- uses: gradle/gradle-build-action@v2
with:
gradle-version: 6.5
```
@ -94,7 +117,7 @@ Moreover, you can use the following aliases:
| `nightly` | The latest [nightly](https://gradle.org/nightly/), fails if none. |
| `release-nightly` | The latest [release nightly](https://gradle.org/release-nightly/), fails if none. |
This can be handy to, for example, automatically test your build with the next Gradle version once a release candidate is out:
This can be handy to automatically verify your build works with the latest release candidate of Gradle:
```yaml
# .github/workflows/test-gradle-rc.yml
@ -110,7 +133,7 @@ jobs:
- uses: actions/setup-java@v1
with:
java-version: 11
- uses: gradle/gradle-build-action@v1
- uses: gradle/gradle-build-action@v2
with:
gradle-version: release-candidate
arguments: build --dry-run # just test build configuration
@ -118,28 +141,34 @@ jobs:
## Caching
This action provides 3 levels of caching to help speed up your GitHub Actions:
- `distributions` caches any distributions downloaded to satisfy a `gradle-version` parameter ;
- `gradle-user-home` caches downloaded dependencies, wrapper distributions, and other stuff from the Gradle User home directory ;
- `project-dot-gradle` caches stored [configuration-cache](https://docs.gradle.org/nightly/userguide/configuration_cache.html) state, saving time configuring the build.
Each of these are enabled by default. To save caching space, you can disable any of them as follows:
```yaml
distributions-cache-enabled: true
gradle-user-home-cache-enabled: true
project-dot-gradle-cache-enabled: true
```
The distributions cache uses a cache key that is unique to the downloaded distribution. This will not change over time.
The `gradle-user-home` and `project-dot-gradle` caches compute a cache key based on the current commit and the Gradle invocation.
As such, these are likely to change on each subsequent run of GitHub actions, allowing the most recent state to always be available in the GitHub actions cache.
By default, this action aims to cache any and all reusable state that may be speed up a subsequent build invocation.
At this time it is not possible to fine-tune this caching. If you have a legitimate use case for fine-grained caching or restricting which files are cached, please raise an issue.
The state that is cached includes:
- Any distributions downloaded to satisfy a `gradle-version` parameter ;
- A subset of the Gradle User Home directory, including downloaded dependencies, wrapper distributions, and the local build cache ;
- Any [configuration-cache](https://docs.gradle.org/nightly/userguide/configuration_cache.html) data stored in the project `.gradle` directory.
To reduce the space required for caching, this action makes a best effort to reduce duplication in cache entries.
Caching is enabled by default. You can disable caching for the action as follows:
```yaml
cache-disabled: true
```
At this time it is not possible to fine-tune the caching performed by this action.
If you have a legitimate use case for fine-grained caching or restricting which files are cached, please raise an issue.
### Cache keys
For cached distributions, the cache key is unique to the downloaded distribution. This will not change over time.
The state of the Gradle User Home and configuration-cache are highly dependent on the Gradle execution, so the cache key is composed of the current commit hash and the GitHub actions job id.
As such, the cache key is likely to change on each subsequent run of GitHub actions.
This allows the most recent state to always be available in the GitHub actions cache.
To reduce duplication between cache entries, certain artifacts are cached independently based on their identity.
Artifacts that are cached independently include downloaded dependencies, downloaded wrapper distributions and generated Gradle API jars.
For example, this means that all jobs executing a particular version of the Gradle wrapper will share common entries for wrapper distributions and for generated Gradle API jars.
### Using the caches read-only
@ -147,21 +176,19 @@ Cache storage space is limited for GitHub actions, and writing new cache entries
In some circumstances, it makes sense for a Gradle invocation to read any existing cache entries but not to write changes back.
For example, you may want to write cache entries for builds on your `main` branch, but not for any PR build invocations.
You can enable read-only caching for any of the caches asfollows:
You can enable read-only caching for any of the caches as follows:
```yaml
distributions-cache-enabled: read-only
gradle-user-home-cache-enabled: read-only
project-dot-gradle-cache-enabled: read-only
cache-read-only: true
```
## Build scans
If your build publishes a [build scan](https://gradle.com/build-scans/) the `gradle-build-action` action will emit the link to the published build scan as an output named `build-scan-url`.
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`.
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:
```yaml
# .github/workflows/gradle-build-pr.yml
@ -169,19 +196,16 @@ name: Run Gradle on PRs
on: pull_request
jobs:
gradle:
strategy:
matrix:
os: [ubuntu-latest, macos-latest, windows-latest]
runs-on: ${{ matrix.os }}
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- uses: actions/setup-java@v1
with:
java-version: 11
- uses: gradle/gradle-build-action@v1
- uses: gradle/gradle-build-action@v2
id: gradle
with:
arguments: build
id: gradle
- name: "Comment build scan url"
uses: actions/github-script@v3
if: github.event_name == 'pull_request' && failure()