mirror of
https://github.com/gradle/actions
synced 2024-11-23 18:02:13 +00:00
Improve documentation
- Provide summary of each action on main page - Extract detailed documentation for each action - Document usage with forked repositories
This commit is contained in:
daz
parent
d731f29856
commit
40c351e1fe
3 changed files with 238 additions and 7 deletions
20
README.md
20
README.md
|
|
@ -2,7 +2,7 @@
|
|||
|
||||
This repository contains a set of GitHub Actions that are useful for building Gradle projects on GitHub.
|
||||
|
||||
## `gradle/actions/setup-gradle`
|
||||
## The `setup-gradle` action
|
||||
|
||||
A simple wrapper around `gradle/gradle-build-action`, removing the deprecated `arguments` parameter (and thus removing the ability to _execute_ gradle).
|
||||
The intention is to eventually deprecate `gradle-build-action` with this being the replacement.
|
||||
|
|
@ -28,18 +28,22 @@ jobs:
|
|||
run: ./gradlew build
|
||||
```
|
||||
|
||||
## `gradle/actions/dependency-submission`
|
||||
See the [`gradle-build-action` documentation](https://github.com/gradle/gradle-build-action/blob/main/README.md) for a full description of this action.
|
||||
|
||||
Generates and submits a dependency graph for a Gradle project. This action is designed to be used in a standalone workflow.
|
||||
The intention is to provide a simple, standardised way to enable Dependency Graph support for Gradle repositories,
|
||||
with a long-term goal of having this functionality enabled by default for Gradle projects on GitHub.
|
||||
## The `dependency-submission` action
|
||||
|
||||
Generates and submits a dependency graph for a Gradle project, allowing GitHub to alert about reported vulnerabilities in your project dependencies.
|
||||
|
||||
|
||||
The following workflow will generate a dependency graph for a Gradle project and submit it immediately to the repository via the
|
||||
Dependency Submission API. For most projects, this default configuration should be all that you need.
|
||||
|
||||
Simply add this as a new workflow file to your repository (eg `.github/workflows/dependency-submission.yml`).
|
||||
|
||||
### Example usage
|
||||
```yaml
|
||||
name: Dependency Submission
|
||||
|
||||
on:
|
||||
workflow_dispatch:
|
||||
push:
|
||||
branches:
|
||||
- main
|
||||
|
|
@ -56,3 +60,5 @@ jobs:
|
|||
- name: Generate and submit dependency graph
|
||||
uses: gradle/actions/dependency-submission@v0
|
||||
```
|
||||
|
||||
See the [full action documentation](dependency-submission/README.md) for more advanced usage scenarios.
|
||||
|
|
|
|||
198
dependency-submission/README.md
Normal file
198
dependency-submission/README.md
Normal file
|
|
@ -0,0 +1,198 @@
|
|||
# The `dependency-submission` action
|
||||
|
||||
Generates and submits a dependency graph for a Gradle project. This action is designed to be used in a standalone workflow.
|
||||
The intention is to provide a simple, standardised way to enable Dependency Graph support for Gradle repositories,
|
||||
with a long-term goal of having this functionality enabled by default for Gradle projects on GitHub.
|
||||
|
||||
## General usage
|
||||
|
||||
The following workflow will generate a dependency graph for a Gradle project and submit it immediately to the repository via the
|
||||
Dependency Submission API. For most projects, this default configuration should be all that you need.
|
||||
|
||||
Simply add this as a new workflow file to your repository (eg `.github/workflows/dependency-submission.yml`).
|
||||
|
||||
```yaml
|
||||
name: Dependency Submission
|
||||
|
||||
on:
|
||||
push:
|
||||
branches:
|
||||
- main
|
||||
|
||||
permissions:
|
||||
contents: write
|
||||
|
||||
jobs:
|
||||
dependency-submission:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- name: Checkout sources
|
||||
uses: actions/checkout@v4
|
||||
- name: Generate and submit dependency graph
|
||||
uses: gradle/actions/dependency-submission@v0
|
||||
```
|
||||
|
||||
### Configuration parameters
|
||||
|
||||
In some cases, the default action configuration will not be sufficient, and additional action parameters will need to be specified.
|
||||
|
||||
See the example below for a summary, and the [Action Metadata file](../dependency-submission/action.yml) for a more detailed description of each input parameter.
|
||||
|
||||
```yaml
|
||||
name: Dependency Submission with advanced config
|
||||
|
||||
on:
|
||||
push:
|
||||
branches:
|
||||
- main
|
||||
|
||||
permissions:
|
||||
contents: read
|
||||
|
||||
jobs:
|
||||
dependency-submission:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- name: Checkout sources
|
||||
uses: actions/checkout@v4
|
||||
- name: Generate and save dependency graph
|
||||
uses: gradle/actions/dependency-submission@v0
|
||||
with:
|
||||
# Use a particular Gradle version instead of the configured wrapper.
|
||||
gradle-version: 8.6-rc-2
|
||||
|
||||
# The gradle project is not in the root of the repository.
|
||||
build-root-directory: my-gradle-project
|
||||
|
||||
# Enable configuration-cache reuse for this build.
|
||||
cache-encryption-key: ${{ secrets.GRADLE_ENCRYPTION_KEY }}
|
||||
|
||||
# Do not attempt to submit the dependency-graph. Save it as a workflow artifact.
|
||||
dependency-graph-action: generate-and-save
|
||||
```
|
||||
|
||||
## Integrating the `dependency-review-action`
|
||||
|
||||
The GitHub [dependency-review-action](https://github.com/actions/dependency-review-action) helps you
|
||||
understand dependency changes (and the security impact of these changes) for a pull request,
|
||||
by comparing the dependency graph for the pull-request with that of the HEAD commit.
|
||||
|
||||
Example of a pull request workflow that executes a build for a pull request and runs the `dependency-review-action`:
|
||||
|
||||
```yaml
|
||||
name: Dependency review for pull requests
|
||||
|
||||
on:
|
||||
pull_request:
|
||||
|
||||
permissions:
|
||||
contents: write
|
||||
|
||||
jobs:
|
||||
dependency-submission:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- name: Checkout sources
|
||||
uses: actions/checkout@v4
|
||||
- name: Generate and submit dependency graph
|
||||
uses: gradle/actions/dependency-submission@v0
|
||||
|
||||
dependency-review:
|
||||
needs: dependency-submission
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- name: Perform dependency review
|
||||
uses: actions/dependency-review-action@v3
|
||||
```
|
||||
|
||||
Note that the `dependency-submission` action submits the dependency graph at the completion of the workflow Job.
|
||||
For this reason, the `dependency-review-action` must be executed in a dependent job, and not as a subsequent step in the job that generates the dependency graph.
|
||||
|
||||
## Usage with pull requests from public forked repositories
|
||||
|
||||
This `contents: write` permission is [not available for any workflow that is triggered by a pull request submitted from a public forked repository](https://docs.github.com/en/actions/security-guides/automatic-token-authentication#permissions-for-the-github_token).
|
||||
This limitation is designed to prevent a malicious pull request from effecting repository changes.
|
||||
|
||||
Because of this restriction, we require 2 separate workflows in order to generate and submit a dependency graph:
|
||||
1. The first workflow runs directly against the pull request sources and will `generate-and-save` the dependency graph.
|
||||
2. The second workflow is triggered on `workflow_run` of the first workflow, and will `retrieve-and-submit` the previously saved dependency graph.
|
||||
|
||||
***Main workflow file***
|
||||
```yaml
|
||||
name: Generate and save dependency graph
|
||||
|
||||
on:
|
||||
pull_request:
|
||||
|
||||
permissions:
|
||||
contents: read # 'write' permission is not available
|
||||
|
||||
jobs:
|
||||
dependency-submission:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- name: Checkout sources
|
||||
uses: actions/checkout@v4
|
||||
- name: Generate and submit dependency graph
|
||||
uses: gradle/actions/dependency-submission@v0
|
||||
with:
|
||||
dependency-graph-action: generate-and-save
|
||||
```
|
||||
|
||||
***Dependent workflow file***
|
||||
```yaml
|
||||
name: Retrieve and submit dependency graph
|
||||
|
||||
on:
|
||||
workflow_run:
|
||||
workflows: ['Generate and save dependency graph']
|
||||
types: [completed]
|
||||
|
||||
permissions:
|
||||
contents: write
|
||||
|
||||
jobs:
|
||||
submit-dependency-graph:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- name: Retrieve and submit dependency graph
|
||||
uses: gradle/actions/dependency-submission@v0
|
||||
with:
|
||||
dependency-graph-action: retrieve-and-submit # Download saved dependency-graph and submit
|
||||
```
|
||||
|
||||
### Integrating `dependency-review-action` for pull requests from public forked repositories
|
||||
|
||||
To integrate the `dependency-review-action` into the pull request workflows above, a third workflow file is required.
|
||||
This workflow will be triggered directly on `pull_request`, but will wait until the dependency graph results are
|
||||
submitted before the dependency review can complete. The period to wait is controlled by the `retry-on-snapshot-warnings` input parameters.
|
||||
|
||||
Here's an example of a separate "Dependency Review" workflow that will wait for 10 minutes for the above PR check workflow to complete.
|
||||
|
||||
```yaml
|
||||
name: dependency-review
|
||||
on:
|
||||
pull_request:
|
||||
|
||||
permissions:
|
||||
contents: read
|
||||
|
||||
jobs:
|
||||
dependency-review:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- name: 'Dependency Review'
|
||||
uses: actions/dependency-review-action@v3
|
||||
with:
|
||||
retry-on-snapshot-warnings: true
|
||||
retry-on-snapshot-warnings-timeout: 600
|
||||
```
|
||||
|
||||
The `retry-on-snapshot-warnings-timeout` (in seconds) needs to be long enough to allow the entire `Generate and save dependency graph` and `Retrieve and submit dependency graph` workflows (above) to complete.
|
||||
|
||||
## Gradle version compatibility
|
||||
|
||||
Dependency-graph generation is compatible with most versions of Gradle >= `5.2`, and is tested regularly against
|
||||
Gradle versions `5.2.1`, `5.6.4`, `6.0.1`, `6.9.4`, `7.1.1` and `7.6.3`, as well as all patched versions of Gradle 8.x.
|
||||
|
||||
A known exception to this is that Gradle `7.0`, `7.0.1` and `7.0.2` are not supported.
|
||||
27
setup-gradle/README.md
Normal file
27
setup-gradle/README.md
Normal file
|
|
@ -0,0 +1,27 @@
|
|||
# The `setup-gradle` action
|
||||
|
||||
This action is a simple wrapper around `gradle/gradle-build-action`, removing the deprecated `arguments` parameter (and thus removing the ability to _execute_ gradle).
|
||||
The intention is to eventually deprecate `gradle-build-action` with this being the replacement.
|
||||
|
||||
### Example usage
|
||||
|
||||
```yaml
|
||||
name: Build
|
||||
|
||||
on:
|
||||
workflow_dispatch:
|
||||
push:
|
||||
|
||||
jobs:
|
||||
build:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- name: Checkout sources
|
||||
uses: actions/checkout@v4
|
||||
- name: Setup Gradle
|
||||
uses: gradle/actions/setup-gradle@v0
|
||||
- name: Build with Gradle
|
||||
run: ./gradlew build
|
||||
```
|
||||
|
||||
See the [`gradle-build-action` documentation](https://github.com/gradle/gradle-build-action/blob/main/README.md) for a full description of this action.
|
||||
Loading…
Reference in a new issue