Improve documentation

- Provide summary of each action on main page
- Extract detailed documentation for each action
- Document usage with forked repositories

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 `dependency-submission` action
-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.
+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.

dependency-submission/README.md

@@ -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.

setup-gradle/README.md

@@ -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.