Update docs for PR comment

This commit is contained in:
daz 2024-01-01 13:48:08 -07:00
parent 333078158e
commit d16a3f4093
No known key found for this signature in database

View File

@ -368,62 +368,57 @@ gradle-home-cache-cleanup: true
## Build reporting ## Build reporting
The `gradle-build-action` collects information about any Gradle executions that occur in a workflow, and reports these via The `gradle-build-action` collects information about any Gradle executions that occur in a workflow, including the root project,
a Job Summary, visible in the GitHub Actions UI. For each Gradle execution, details about the invocation are listed, together with requested tasks, build outcome and any Build Scan link generated. Details of cache entries read and written are also collected.
a link to any Build Scan® published. These details are compiled into a Job Summary, which is visible in the GitHub Actions UI.
Generation of a Job Summary is enabled by default. If this is not desired, it can be disable as follows: Generation of a Job Summary is enabled by default for all Jobs using the `gradle-build-action`. This feature can be configured
so that a Job Summary is never generated, or so that a Job Summary is only generated on build failure:
```yaml ```yaml
generate-job-summary: false add-job-summary: 'on-failure' # Valid values are 'always' (default), 'never', and 'on-failure'
``` ```
Note that the action collects information about Gradle invocations via an [Initialization Script](https://docs.gradle.org/current/userguide/init_scripts.html#sec:using_an_init_script) ### Adding Job Summary as a Pull Request comment
located at `USER_HOME/.gradle/init.d/build-result-capture.init.gradle`.
If you are using init scripts for the [Gradle Enterprise Gradle Plugin](https://plugins.gradle.org/plugin/com.gradle.enterprise) like
[`scans-init.gradle` or `gradle-enterprise-init.gradle`](https://docs.gradle.com/enterprise/gradle-plugin/#scans_gradle_com),
you'll need to ensure these files are applied prior to `build-result-capture.init.gradle`.
Since Gradle applies init scripts in alphabetical order, one way to ensure this is via file naming.
### Build Scan® link as Step output It is sometimes more convenient to view the results of a GitHub Actions Job directly from the Pull Request that triggered
the Job. For this purpose you can configure the action so that Job Summary data is added as a Pull Request comment.
As well as reporting the [Build Scan](https://gradle.com/build-scans/) link in the Job Summary,
the `gradle-build-action` action makes this link available as a Step output named `build-scan-url`.
You can then use that link in subsequent actions of your workflow. For example:
```yaml ```yaml
# .github/workflows/gradle-build-pr.yml name: CI
name: Run Gradle on PRs on:
on: pull_request pull_request:
permissions:
pull-requests: write
jobs: jobs:
gradle: run-gradle-build:
runs-on: ubuntu-latest runs-on: ubuntu-latest
steps: steps:
- name: Checkout project sources - name: Checkout project sources
uses: actions/checkout@v4 uses: actions/checkout@v4
- name: Setup Gradle - name: Setup Gradle
uses: gradle/gradle-build-action@v2 uses: gradle/gradle-build-action@v3
- name: Run build with Gradle wrapper
id: gradle
run: ./gradlew build --scan
- name: "Add Build Scan URL as PR comment"
uses: actions/github-script@v5
if: github.event_name == 'pull_request' && failure()
with: with:
github-token: ${{secrets.GITHUB_TOKEN}} add-job-summary-as-pr-comment: on-failure # Valid values are 'never' (default), 'always', and 'on-failure'
script: | - run: ./gradlew build --scan
github.rest.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 }}'
})
``` ```
### Saving build outputs Note that in order to add a Pull Request comment, the workflow must be configured with the `pull-requests: write` permission.
By default, a GitHub Actions workflow using `gradle-build-action` will record the log output and any Build Scan links for your build,
but any output files generated by the build will not be saved. ### Build Scan® link as Step output
As well as reporting all [Build Scan](https://gradle.com/build-scans/) links in the Job Summary,
the `gradle-build-action` action makes this link available an an output of any Step that executes Gradle.
The output name is `build-scan-url`. You can then use the build scan link in subsequent actions of your workflow.
### Saving arbitrary build outputs
By default, a GitHub Actions workflow using `gradle-build-action` will record the log output and any Build Scan
links for your build, but any output files generated by the build will not be saved.
To save selected files from your build execution, you can use the core [Upload-Artifact](https://github.com/actions/upload-artifact) action. To save selected files from your build execution, you can use the core [Upload-Artifact](https://github.com/actions/upload-artifact) action.
For example: For example:
@ -447,6 +442,14 @@ jobs:
path: build/reports/ path: build/reports/
``` ```
### Use of custom init-scripts in Gradle User Home
Note that the action collects information about Gradle invocations via an [Initialization Script](https://docs.gradle.org/current/userguide/init_scripts.html#sec:using_an_init_script)
located at `USER_HOME/.gradle/init.d/gradle-build-action.build-result-capture.init.gradle`.
If you are adding any custom init scripts to the `USER_HOME/.gradle/init.d` directory, it may be necessary to ensure these files are applied prior to `gradle-build-action.build-result-capture.init.gradle`.
Since Gradle applies init scripts in alphabetical order, one way to ensure this is via file naming.
## Support for GitHub Enterprise Server (GHES) ## Support for GitHub Enterprise Server (GHES)
You can use the `gradle-build-action` on GitHub Enterprise Server, and benefit from the improved integration with Gradle. Depending on the version of GHES you are running, certain features may be limited: You can use the `gradle-build-action` on GitHub Enterprise Server, and benefit from the improved integration with Gradle. Depending on the version of GHES you are running, certain features may be limited: