gradle-build-action/README.md

198 lines
6.3 KiB
Markdown
Raw Normal View History

# Execute Gradle builds in GitHub Actions workflows
2019-09-20 17:06:59 -04:00
This GitHub Action can be used to execute a Gradle build on any platform supported by GitHub Actions.
2019-09-20 17:06:59 -04:00
2019-09-21 10:01:53 -04:00
## Usage
2019-09-20 17:06:59 -04:00
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.
2019-09-23 06:10:22 -04:00
2019-09-21 10:01:53 -04:00
```yaml
2019-09-23 07:00:12 -04:00
# .github/workflows/gradle-build-pr.yml
2019-09-21 10:01:53 -04:00
name: Run Gradle on PRs
on: pull_request
2019-09-21 10:01:53 -04:00
jobs:
gradle:
strategy:
matrix:
os: [ubuntu-latest, macos-latest, windows-latest]
runs-on: ${{ matrix.os }}
steps:
2020-06-14 06:57:10 -04:00
- uses: actions/checkout@v2
2019-09-21 10:01:53 -04:00
- uses: actions/setup-java@v1
with:
java-version: 11
- uses: gradle/gradle-build-action@v1
2019-09-21 10:01:53 -04:00
with:
arguments: build
```
## Gradle arguments
The `arguments` input can used to pass arbitrary arguments to the `gradle` command line.
Here are some valid examples:
```yaml
arguments: build
arguments: check --scan
arguments: some arbitrary tasks
arguments: build -PgradleProperty=foo
arguments: build -DsystemProperty=bar
....
```
See `gradle --help` for more information.
2020-02-14 00:46:51 -05:00
If you need to pass environment variables, simply use the GitHub Actions workflow syntax:
2019-09-21 10:01:53 -04:00
```yaml
- uses: gradle/gradle-build-action@v1
2019-09-21 10:01:53 -04:00
env:
CI: true
```
## Run a build from a different directory
```yaml
- uses: gradle/gradle-build-action@v1
2019-09-21 10:01:53 -04:00
with:
build-root-directory: some/subdirectory
```
## Use a specific `gradle` executable
```yaml
- uses: gradle/gradle-build-action@v1
2019-09-21 10:01:53 -04:00
with:
gradle-executable: path/to/gradle
```
## Use a Gradle wrapper from a different directory
```yaml
- uses: gradle/gradle-build-action@v1
with:
gradle-executable: path/to/gradlew
```
2019-09-21 10:04:03 -04:00
## Setup and use a declared Gradle version
2019-09-21 10:01:53 -04:00
```yaml
- uses: gradle/gradle-build-action@v1
2019-09-21 10:01:53 -04:00
with:
2020-06-14 06:57:10 -04:00
gradle-version: 6.5
2019-09-21 10:01:53 -04:00
```
`gradle-version` can be set to any valid Gradle version.
Moreover, you can use the following aliases:
| Alias | Selects |
| --- |---|
| `wrapper` | The Gradle wrapper's version (default, useful for matrix builds) |
| `current` | The current [stable release](https://gradle.org/install/) |
| `release-candidate` | The current [release candidate](https://gradle.org/release-candidate/) if any, otherwise fallback to `current` |
| `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. |
2019-09-21 10:01:53 -04:00
2019-09-23 06:10:22 -04:00
This can be handy to, for example, automatically test your build with the next Gradle version once a release candidate is out:
2019-09-21 10:01:53 -04:00
```yaml
2019-09-23 07:00:12 -04:00
# .github/workflows/test-gradle-rc.yml
2019-09-21 10:01:53 -04:00
name: Test latest Gradle RC
on:
schedule:
- cron: 0 0 * * * # daily
jobs:
gradle-rc:
runs-on: ubuntu-latest
steps:
2020-06-14 06:57:10 -04:00
- uses: actions/checkout@v2
2019-09-21 10:01:53 -04:00
- uses: actions/setup-java@v1
with:
java-version: 11
- uses: gradle/gradle-build-action@v1
2019-09-21 10:01:53 -04:00
with:
gradle-version: release-candidate
2019-09-21 10:01:53 -04:00
arguments: build --dry-run # just test build configuration
```
2020-06-15 10:23:01 -04:00
## 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.
2020-06-15 10:23:01 -04:00
Each of these are enabled by default. To save caching space, you can disable any of them as follows:
2020-06-15 10:23:01 -04:00
```yaml
distributions-cache-enabled: true
gradle-user-home-cache-enabled: true
project-dot-gradle-cache-enabled: true
2020-06-15 10:23:01 -04:00
```
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.
2020-06-15 10:23:01 -04:00
By default, this action aims to cache any and all reusable state that may be speed up a subsequent build invocation.
2020-06-15 10:23:01 -04:00
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.
2020-06-15 10:23:01 -04:00
### Using the caches read-only
Cache storage space is limited for GitHub actions, and writing new cache entries can trigger the deletion of exising 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:
```yaml
distributions-cache-enabled: read-only
gradle-user-home-cache-enabled: read-only
project-dot-gradle-cache-enabled: read-only
```
2020-06-15 10:23:01 -04:00
## Build scans
2019-09-21 10:01:53 -04:00
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`.
2019-09-21 10:01:53 -04:00
You can then use that link in subsequent actions of your workflow.
For example:
```yaml
2019-09-23 07:00:12 -04:00
# .github/workflows/gradle-build-pr.yml
name: Run Gradle on PRs
2020-04-18 11:10:08 -04:00
on: pull_request
jobs:
gradle:
strategy:
matrix:
os: [ubuntu-latest, macos-latest, windows-latest]
runs-on: ${{ matrix.os }}
steps:
2020-06-14 06:57:10 -04:00
- uses: actions/checkout@v2
- uses: actions/setup-java@v1
with:
java-version: 11
- uses: gradle/gradle-build-action@v1
with:
arguments: build
id: gradle
- name: "Comment build scan url"
uses: actions/github-script@v3
if: github.event_name == 'pull_request' && failure()
with:
github-token: ${{secrets.GITHUB_TOKEN}}
script: |
github.issues.createComment({
issue_number: context.issue.number,
owner: context.repo.owner,
repo: context.repo.repo,
body: '❌ ${{ github.workflow }} failed: ${{ steps.gradle.outputs.build-scan-url }}'
})
```