From d16a3f4093231338d4f7006781c19a48e2d2cf26 Mon Sep 17 00:00:00 2001 From: daz Date: Mon, 1 Jan 2024 13:48:08 -0700 Subject: [PATCH] Update docs for PR comment --- README.md | 79 +++++++++++++++++++++++++++++-------------------------- 1 file changed, 41 insertions(+), 38 deletions(-) diff --git a/README.md b/README.md index b22bc97..2e2ae1c 100644 --- a/README.md +++ b/README.md @@ -368,62 +368,57 @@ gradle-home-cache-cleanup: true ## Build reporting -The `gradle-build-action` collects information about any Gradle executions that occur in a workflow, and reports these via -a Job Summary, visible in the GitHub Actions UI. For each Gradle execution, details about the invocation are listed, together with -a link to any Build Scan® published. +The `gradle-build-action` collects information about any Gradle executions that occur in a workflow, including the root project, +requested tasks, build outcome and any Build Scan link generated. Details of cache entries read and written are also collected. +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 -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) -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. +### Adding Job Summary as a Pull Request comment -### 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 -# .github/workflows/gradle-build-pr.yml -name: Run Gradle on PRs -on: pull_request +name: CI +on: + pull_request: + +permissions: + pull-requests: write + jobs: - gradle: + run-gradle-build: runs-on: ubuntu-latest steps: - name: Checkout project sources uses: actions/checkout@v4 - name: Setup Gradle - uses: gradle/gradle-build-action@v2 - - 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() + uses: gradle/gradle-build-action@v3 with: - github-token: ${{secrets.GITHUB_TOKEN}} - script: | - 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 }}' - }) + add-job-summary-as-pr-comment: on-failure # Valid values are 'never' (default), 'always', and 'on-failure' + - run: ./gradlew build --scan ``` -### 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. For example: @@ -447,6 +442,14 @@ jobs: 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) 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: