gradle-build-action/README.md

253 lines
8.6 KiB
Markdown
Raw Normal View History

# Execute Gradle builds in GitHub Actions workflows
2019-09-20 21:06:59 +00:00
This GitHub Action can be used to execute a Gradle build on any platform supported by GitHub Actions.
2019-09-20 21:06:59 +00:00
2019-09-21 14:01:53 +00:00
## Usage
2019-09-20 21:06:59 +00:00
2021-09-28 17:30:55 +00:00
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.
2019-09-23 10:10:22 +00:00
2019-09-21 14:01:53 +00:00
```yaml
2019-09-23 11:00:12 +00:00
# .github/workflows/gradle-build-pr.yml
2019-09-21 14:01:53 +00:00
name: Run Gradle on PRs
on: pull_request
2019-09-21 14:01:53 +00:00
jobs:
gradle:
strategy:
matrix:
os: [ubuntu-latest, macos-latest, windows-latest]
runs-on: ${{ matrix.os }}
steps:
2020-06-14 10:57:10 +00:00
- uses: actions/checkout@v2
2019-09-21 14:01:53 +00:00
- uses: actions/setup-java@v1
with:
java-version: 11
2021-09-28 17:30:55 +00:00
- uses: gradle/gradle-build-action@v2
2019-09-21 14:01:53 +00:00
with:
arguments: build
```
2021-09-28 17:30:55 +00:00
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
2019-09-21 14:01:53 +00:00
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.
2019-09-21 14:01:53 +00:00
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
2019-09-21 14:01:53 +00:00
```
See `gradle --help` for more information.
2021-09-28 17:30:55 +00:00
If you need to pass environment variables, use the GitHub Actions workflow syntax:
2019-09-21 14:01:53 +00:00
```yaml
2021-09-28 17:30:55 +00:00
- uses: gradle/gradle-build-action@v2
2019-09-21 14:01:53 +00:00
env:
CI: true
2021-09-28 17:30:55 +00:00
with:
arguments: build
2019-09-21 14:01:53 +00:00
```
2021-09-28 17:30:55 +00:00
### 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.
2019-09-21 14:01:53 +00:00
```yaml
2021-09-28 17:30:55 +00:00
- uses: gradle/gradle-build-action@v2
2019-09-21 14:01:53 +00:00
with:
build-root-directory: some/subdirectory
```
2021-09-28 17:30:55 +00:00
### 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.
2019-09-21 14:01:53 +00:00
```yaml
2021-09-28 17:30:55 +00:00
- uses: gradle/gradle-build-action@v2
2019-09-21 14:01:53 +00:00
with:
2021-09-28 17:30:55 +00:00
gradle-executable: /path/to/installed/gradle
2019-09-21 14:01:53 +00:00
```
2021-09-28 17:30:55 +00:00
This mechanism can also be used to target a Gradle wrapper script that is located in a non-default location.
2021-09-28 17:30:55 +00:00
### Download, install and use a specific Gradle version
The `gradle-build-action` is able to download and install a specific Gradle version to execute.
2019-09-21 14:01:53 +00:00
```yaml
2021-09-28 17:30:55 +00:00
- uses: gradle/gradle-build-action@v2
2019-09-21 14:01:53 +00:00
with:
2020-06-14 10:57:10 +00:00
gradle-version: 6.5
2019-09-21 14:01:53 +00: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 14:01:53 +00:00
2021-09-28 17:30:55 +00:00
This can be handy to automatically verify your build works with the latest release candidate of Gradle:
2019-09-21 14:01:53 +00:00
```yaml
2019-09-23 11:00:12 +00:00
# .github/workflows/test-gradle-rc.yml
2019-09-21 14:01:53 +00:00
name: Test latest Gradle RC
on:
schedule:
- cron: 0 0 * * * # daily
jobs:
gradle-rc:
runs-on: ubuntu-latest
steps:
2020-06-14 10:57:10 +00:00
- uses: actions/checkout@v2
2019-09-21 14:01:53 +00:00
- uses: actions/setup-java@v1
with:
java-version: 11
2021-09-28 17:30:55 +00:00
- uses: gradle/gradle-build-action@v2
2019-09-21 14:01:53 +00:00
with:
gradle-version: release-candidate
2019-09-21 14:01:53 +00:00
arguments: build --dry-run # just test build configuration
```
2020-06-15 14:23:01 +00:00
## Caching
2021-09-28 17:30:55 +00: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 14:23:01 +00:00
2021-09-28 17:30:55 +00:00
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.
2020-06-15 14:23:01 +00:00
2021-09-28 17:30:55 +00:00
To reduce the space required for caching, this action makes a best effort to reduce duplication in cache entries.
2020-06-15 14:23:01 +00:00
2021-09-28 17:30:55 +00:00
Caching is enabled by default. You can disable caching for the action as follows:
2020-06-15 14:23:01 +00:00
```yaml
2021-09-28 17:30:55 +00:00
cache-disabled: true
2020-06-15 14:23:01 +00:00
```
2021-09-28 17:30:55 +00:00
### Cache keys
2020-06-15 14:23:01 +00:00
For cached distributions outside of Gradle User Home, the cache key is unique to the downloaded distribution. This will not change over time.
2020-06-15 14:23:01 +00:00
2021-09-28 17:30:55 +00:00
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.
2020-06-15 14:23:01 +00: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.
2021-09-28 17:30:55 +00:00
You can enable read-only caching for any of the caches as follows:
```yaml
# Only write to the cache for builds on the 'main' branch.
# Builds on other branches will only read existing entries from the cache.
cache-read-only: ${{ github.ref != 'refs/heads/main' }}
```
### Gradle User Home cache tuning
As well as any wrapper distributions, the action will attempt to save and restore the `caches` and `notifications` directories from Gradle User Home.
The contents to be cached can be fine tuned by including and excluding certain paths with Gradle User Home.
```yaml
# Cache downloaded JDKs in addition to the default directories.
gradle-home-cache-includes: |
caches
notifications
jdks
# Exclude the local build-cache from the directories cached.
gradle-home-cache-excludes: |
caches/build-cache-1
```
You can specify any number of fixed paths or patterns to include or exclude.
File pattern support is documented at https://docs.github.com/en/actions/learn-github-actions/workflow-syntax-for-github-actions#patterns-to-match-file-paths.
### Cache debugging
It is possible to enable additional debug logging for cache operations. You do via the `GRADLE_BUILD_ACTION_CACHE_DEBUG_ENABLED` environment variable:
```yaml
env:
GRADLE_BUILD_ACTION_CACHE_DEBUG_ENABLED: true
```
Note that this setting will also prevent certain cache operations from running in parallel, further assisting with debugging.
2020-06-15 14:23:01 +00:00
## Build scans
2019-09-21 14:01:53 +00:00
2021-09-28 17:30:55 +00:00
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`.
2021-09-28 17:30:55 +00:00
You can then use that link in subsequent actions of your workflow. For example:
```yaml
2019-09-23 11:00:12 +00:00
# .github/workflows/gradle-build-pr.yml
name: Run Gradle on PRs
2020-04-18 15:10:08 +00:00
on: pull_request
jobs:
gradle:
2021-09-28 17:30:55 +00:00
runs-on: ubuntu-latest
steps:
2020-06-14 10:57:10 +00:00
- uses: actions/checkout@v2
- uses: actions/setup-java@v1
with:
java-version: 11
2021-09-28 17:30:55 +00:00
- uses: gradle/gradle-build-action@v2
id: gradle
with:
arguments: build
- 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 }}'
})
```